diff --git a/src/semble/agents/claude.md b/src/semble/agents/claude.md index de79bf17..65f19039 100644 --- a/src/semble/agents/claude.md +++ b/src/semble/agents/claude.md @@ -1,46 +1,31 @@ --- name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question. -tools: Bash, Read +tools: mcp__semble__search, mcp__semble__find_related, Bash, Read --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with Read. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via Bash only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/codex.toml b/src/semble/agents/codex.toml index ba422400..7c96924d 100644 --- a/src/semble/agents/codex.toml +++ b/src/semble/agents/codex.toml @@ -1,44 +1,29 @@ name = "semble_search" description = "Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question." developer_instructions = """ -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +If the `mcp__semble__search` tool is available in your toolset, prefer it over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). If the MCP tools are not available, use the CLI fallback below. -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary, when available) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with the read tool. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via the shell tool only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (when the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). """ diff --git a/src/semble/agents/commandcode.md b/src/semble/agents/commandcode.md index 8691bca4..d7718fb2 100644 --- a/src/semble/agents/commandcode.md +++ b/src/semble/agents/commandcode.md @@ -1,46 +1,31 @@ --- name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question. -tools: bash, read_file +tools: shell_command, read_file, mcp__semble__search, mcp__semble__find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with read_file. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via shell_command only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/copilot.md b/src/semble/agents/copilot.md index de79bf17..6857e837 100644 --- a/src/semble/agents/copilot.md +++ b/src/semble/agents/copilot.md @@ -1,46 +1,31 @@ --- name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question. -tools: Bash, Read +tools: Bash, Read, semble/search, semble/find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `semble/search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `semble/find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `semble/search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with Read. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `semble/find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble/search` call. +6. Use grep via Bash only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/cursor.md b/src/semble/agents/cursor.md index 944e7c59..2f2001c3 100644 --- a/src/semble/agents/cursor.md +++ b/src/semble/agents/cursor.md @@ -3,43 +3,28 @@ name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question. --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +If the `mcp__semble__search` tool is available in your toolset, prefer it over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). If the MCP tools are not available, use the CLI fallback below. -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary, when available) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with the read tool. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via the shell tool only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (when the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/gemini.md b/src/semble/agents/gemini.md index d7ab6258..3a9f8d4a 100644 --- a/src/semble/agents/gemini.md +++ b/src/semble/agents/gemini.md @@ -4,45 +4,32 @@ description: Code search agent for exploring any codebase. Use for finding code tools: - run_shell_command - read_file + - mcp_semble_search + - mcp_semble_find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp_semble_search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp_semble_find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp_semble_search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with read_file. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp_semble_find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp_semble_search` call. +6. Use grep via run_shell_command only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/grok.md b/src/semble/agents/grok.md index 2779dacb..b6d127e9 100644 --- a/src/semble/agents/grok.md +++ b/src/semble/agents/grok.md @@ -3,43 +3,28 @@ name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over grep/read_file for any semantic or exploratory question. --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +If the `mcp__semble__search` tool is available in your toolset, prefer it over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). If the MCP tools are not available, use the CLI fallback below. -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary, when available) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with the read tool. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via the shell tool only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (when the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/kilo.md b/src/semble/agents/kilo.md index aa962db5..ba809756 100644 --- a/src/semble/agents/kilo.md +++ b/src/semble/agents/kilo.md @@ -5,45 +5,32 @@ mode: subagent permission: bash: allow read: allow + semble_search: allow + semble_find_related: allow --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `semble_search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `semble_find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `semble_search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with Read. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `semble_find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble_search` call. +6. Use grep via Bash only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/kiro.md b/src/semble/agents/kiro.md index 4c78ad76..c52717ec 100644 --- a/src/semble/agents/kiro.md +++ b/src/semble/agents/kiro.md @@ -4,45 +4,32 @@ description: Code search agent for exploring any codebase. Use for finding code tools: - shell - read + - mcp_semble_search + - mcp_semble_find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp_semble_search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp_semble_find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp_semble_search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with the read tool. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp_semble_find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp_semble_search` call. +6. Use grep via the shell tool only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/opencode.md b/src/semble/agents/opencode.md index aa962db5..ba809756 100644 --- a/src/semble/agents/opencode.md +++ b/src/semble/agents/opencode.md @@ -5,45 +5,32 @@ mode: subagent permission: bash: allow read: allow + semble_search: allow + semble_find_related: allow --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `semble_search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `semble_find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `semble_search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with Read. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `semble_find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble_search` call. +6. Use grep via Bash only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/pi.md b/src/semble/agents/pi.md index 944e7c59..2f2001c3 100644 --- a/src/semble/agents/pi.md +++ b/src/semble/agents/pi.md @@ -3,43 +3,28 @@ name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question. --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +If the `mcp__semble__search` tool is available in your toolset, prefer it over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). If the MCP tools are not available, use the CLI fallback below. -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary, when available) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with the read tool. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via the shell tool only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (when the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/qwen.md b/src/semble/agents/qwen.md index d7ab6258..f2c562d8 100644 --- a/src/semble/agents/qwen.md +++ b/src/semble/agents/qwen.md @@ -4,45 +4,32 @@ description: Code search agent for exploring any codebase. Use for finding code tools: - run_shell_command - read_file + - mcp__semble__search + - mcp__semble__find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with read_file. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via run_shell_command only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/reasonix.md b/src/semble/agents/reasonix.md index 2b51a182..80cd220b 100644 --- a/src/semble/agents/reasonix.md +++ b/src/semble/agents/reasonix.md @@ -2,46 +2,31 @@ name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over bash/grep for any semantic or exploratory question. runAs: subagent -allowed-tools: bash, read_file +allowed-tools: bash, read_file, mcp__semble__search, mcp__semble__find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with read_file. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via bash only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/src/semble/agents/zcode.md b/src/semble/agents/zcode.md index de79bf17..af0ea2f0 100644 --- a/src/semble/agents/zcode.md +++ b/src/semble/agents/zcode.md @@ -1,46 +1,31 @@ --- name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question. -tools: Bash, Read +tools: Bash, Read, mcp__semble__search, mcp__semble__find_related --- -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: +The `semble` MCP server is available with two tools. Prefer them over the CLI: the server keeps the index in memory, so each search takes tens of milliseconds, whereas the CLI starts a fresh process per call (~5 s each). -```bash -semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise -semble search "save_pretrained" ./my-project # full chunk content -semble search "save model to disk" ./my-project --top-k 10 # more results -``` +### MCP tools (primary path) -Results are cached automatically on first run and invalidated when files change. +- `mcp__semble__search` — find code by describing what it does or naming a symbol/identifier, not by error messages. Parameters: `query` (natural-language or code query), `repo` (local path or git URL; accepts a list of several paths/URLs — result paths are then prefixed with the repo name), `top_k` (number of results, default 5), `max_snippet_lines` (default 10 = signature + first body lines; 0 = location only; omit for the full chunk), `content` (`docs`, `config`, or `all`; defaults to code). +- `mcp__semble__find_related` — discover code similar to a known location. Parameters: `file_path` and `line` from a prior search result, plus the same `repo`, `top_k`, `max_snippet_lines`, `content`. -Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: +### Workflow -```bash -semble search "deployment guide" ./my-project --content docs -semble search "database host port" ./my-project --content config -semble search "authentication" ./my-project --content all -``` +1. Start with `mcp__semble__search`; batch independent searches in parallel. +2. Navigate directly to the returned file and line with Read. Do not re-search or grep for the same content. +3. Use `content` as `docs` for documentation and prose, `config` for config files, or `all` for everything. +4. Optionally use `mcp__semble__find_related` with a promising result's `file_path` and `line` to discover related implementations. +5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `mcp__semble__search` call. +6. Use grep via Bash only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): +### CLI fallback (only if the MCP tools are unavailable) ```bash +semble search "authentication flow" ./my-project --max-snippet-lines 10 # first 10 lines only, concise +semble search "save model to disk" ./my-project --content all --top-k 10 # everything, more results semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location: - -```bash -semble search "invoice endpoint" ./service-a ../service-b -``` - If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. - -### Workflow - -1. Start with `semble search` to find relevant chunks. The index is built and cached automatically. -2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. -3. Navigate directly to the returned file and line. Do not re-search or grep for the same content. -4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one `semble search` call. -6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function). diff --git a/tests/test_cli.py b/tests/test_cli.py index 2b6a9ac3..b48ca940 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -269,13 +269,17 @@ def test_maybe_save_index_logs_error_on_save_failure(capsys: pytest.CaptureFixtu assert "Error saving index" in capsys.readouterr().err -def test_agent_file_tools_are_bash_only() -> None: - """The agent file must list only Bash and Read — no MCP tools that require schema loading.""" +def test_agent_file_tools_allow_mcp_plus_bash_and_read() -> None: + """The agent file allows the semble MCP tools alongside Bash and Read.""" frontmatter = files("semble").joinpath("agents/claude.md").read_text(encoding="utf-8").split("---")[1] tools_line = next(line for line in frontmatter.splitlines() if line.startswith("tools:")) tools = [t.strip() for t in tools_line.removeprefix("tools:").split(",")] - assert set(tools) == {"Bash", "Read"}, f"Unexpected tools in agent file: {tools}" - assert not any("mcp__" in t for t in tools) + assert set(tools) == { + "mcp__semble__search", + "mcp__semble__find_related", + "Bash", + "Read", + }, f"Unexpected tools in agent file: {tools}" def _make_valid_index_dir( diff --git a/tests/test_installer.py b/tests/test_installer.py index 90f57952..e0a1be88 100644 --- a/tests/test_installer.py +++ b/tests/test_installer.py @@ -505,6 +505,132 @@ def test_apply_subagent_pins_version(tmp_path): assert '"semble[mcp]"' not in text +@pytest.mark.parametrize( + ("agent_id", "gate_snippets"), + [ + ("claude", ["tools: mcp__semble__search, mcp__semble__find_related, Bash, Read"]), + ( + "opencode", + ["bash: allow", "read: allow", "semble_search: allow", "semble_find_related: allow"], + ), + ( + "kilo", + ["bash: allow", "read: allow", "semble_search: allow", "semble_find_related: allow"], + ), + ], +) +def test_subagent_gate_lists_mcp_tools_with_original_entries(tmp_path, agent_id, gate_snippets): + """Tier A definitions allow the confirmed semble MCP tools alongside the original shell/read entries.""" + agent = next(a for a in AGENTS if a.id == agent_id) + dest = tmp_path / agent.subagent_path.name + assert _apply_subagent(replace(agent, subagent_path=dest), "install").action == "created" + text = dest.read_text() + for snippet in gate_snippets: + assert snippet in text + + +@pytest.mark.parametrize( + ("agent_id", "mcp_tools"), + [ + ("claude", ["mcp__semble__search", "mcp__semble__find_related"]), + ("opencode", ["semble_search", "semble_find_related"]), + ("kilo", ["semble_search", "semble_find_related"]), + ], +) +def test_subagent_body_is_mcp_first_with_cli_fallback(tmp_path, agent_id, mcp_tools): + """Tier A bodies reference the MCP tools by name and keep a CLI fallback with the pinned uvx line.""" + agent = next(a for a in AGENTS if a.id == agent_id) + dest = tmp_path / agent.subagent_path.name + _apply_subagent(replace(agent, subagent_path=dest), "install") + text = dest.read_text() + for tool in mcp_tools: + assert f"`{tool}`" in text + assert "CLI fallback" in text + assert f'uvx --from "{SEMBLE_PIN}" semble' in text + assert '"semble[mcp]"' not in text + + +@pytest.mark.parametrize( + ("agent_id", "gate_snippets"), + [ + ("gemini", ["- run_shell_command", "- read_file", "- mcp_semble_search", "- mcp_semble_find_related"]), + ("qwen", ["- run_shell_command", "- read_file", "- mcp__semble__search", "- mcp__semble__find_related"]), + ("copilot", ["tools: Bash, Read, semble/search, semble/find_related"]), + ("kiro", ["- shell", "- read", "- mcp_semble_search", "- mcp_semble_find_related"]), + ("zcode", ["tools: Bash, Read, mcp__semble__search, mcp__semble__find_related"]), + ("commandcode", ["tools: shell_command, read_file, mcp__semble__search, mcp__semble__find_related"]), + ("reasonix", ["allowed-tools: bash, read_file, mcp__semble__search, mcp__semble__find_related"]), + ], +) +def test_subagent_gate_lists_mcp_tools_tier_b(tmp_path, agent_id, gate_snippets): + """Confirmed Tier B definitions allow the harness-specific semble MCP tools alongside shell/read entries.""" + agent = next(a for a in AGENTS if a.id == agent_id) + dest = tmp_path / agent.subagent_path.name + assert _apply_subagent(replace(agent, subagent_path=dest), "install").action == "created" + text = dest.read_text() + for snippet in gate_snippets: + assert snippet in text + + +@pytest.mark.parametrize( + ("agent_id", "mcp_tools"), + [ + ("gemini", ["mcp_semble_search", "mcp_semble_find_related"]), + ("qwen", ["mcp__semble__search", "mcp__semble__find_related"]), + ("copilot", ["semble/search", "semble/find_related"]), + ("kiro", ["mcp_semble_search", "mcp_semble_find_related"]), + ("zcode", ["mcp__semble__search", "mcp__semble__find_related"]), + ("commandcode", ["mcp__semble__search", "mcp__semble__find_related"]), + ("reasonix", ["mcp__semble__search", "mcp__semble__find_related"]), + ], +) +def test_subagent_body_is_mcp_first_with_cli_fallback_tier_b(tmp_path, agent_id, mcp_tools): + """Tier B bodies reference the harness-specific MCP tools and keep a CLI fallback with the pinned uvx line.""" + agent = next(a for a in AGENTS if a.id == agent_id) + dest = tmp_path / agent.subagent_path.name + _apply_subagent(replace(agent, subagent_path=dest), "install") + text = dest.read_text() + for tool in mcp_tools: + assert f"`{tool}`" in text + assert "CLI fallback" in text + assert f'uvx --from "{SEMBLE_PIN}" semble' in text + assert '"semble[mcp]"' not in text + + +@pytest.mark.parametrize( + ("agent_id", "unchanged_markers"), + [ + ("cursor", ["name: semble-search", "description: Code search agent for exploring any codebase"]), + ("codex", ['name = "semble_search"', 'description = "Code search agent for exploring any codebase']), + ("pi", ["name: semble-search", "description: Code search agent for exploring any codebase"]), + ("grok", ["name: semble-search", "description: Code search agent for exploring any codebase"]), + ], +) +def test_subagent_frontmatter_unchanged_tier_c(tmp_path, agent_id, unchanged_markers): + """Tier C definitions keep their frontmatter untouched (no tool gate to extend).""" + agent = next(a for a in AGENTS if a.id == agent_id) + dest = tmp_path / agent.subagent_path.name + _apply_subagent(replace(agent, subagent_path=dest), "install") + text = dest.read_text() + for marker in unchanged_markers: + assert marker in text + assert "tools:" not in text + + +@pytest.mark.parametrize("agent_id", ["cursor", "codex", "pi", "grok"]) +def test_subagent_body_is_mcp_first_tier_c(tmp_path, agent_id): + """Tier C bodies reference the installer's MCP tool names and keep a CLI fallback with the pinned uvx line.""" + agent = next(a for a in AGENTS if a.id == agent_id) + dest = tmp_path / agent.subagent_path.name + _apply_subagent(replace(agent, subagent_path=dest), "install") + text = dest.read_text() + assert "`mcp__semble__search`" in text + assert "`mcp__semble__find_related`" in text + assert "CLI fallback" in text + assert f'uvx --from "{SEMBLE_PIN}" semble' in text + assert '"semble[mcp]"' not in text + + def test_is_detected(monkeypatch, tmp_path): """is_detected returns True when binary is on PATH or config dir exists.""" agent = next(a for a in AGENTS if a.id == "claude")