From 56e2cab97d3395ed3efa331516e14128dbb7c181 Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:31:06 +0200 Subject: [PATCH 01/13] Update install instructions and semble init --- README.md | 60 ++++-------- docs/installation.md | 223 +++++++++++++++++++++++++++++++++++++++++++ src/semble/cli.py | 27 ++++-- 3 files changed, 261 insertions(+), 49 deletions(-) create mode 100644 docs/installation.md diff --git a/README.md b/README.md index 5881245..0cbc4eb 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,8 @@ [MCP Server](#mcp-server) • [Bash / AGENTS.md](#bash-agentsmd) • [CLI](#cli) • -[Benchmarks](#benchmarks) +[Benchmarks](#benchmarks) • +[Installation guide](docs/installation.md) @@ -38,7 +39,7 @@ Add Semble to Claude Code (requires [uv](https://docs.astral.sh/uv/getting-start claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` -Using Codex, OpenCode, or Cursor? See [MCP Server](#mcp-server) for setup instructions. +Using Gemini CLI, Cursor, Codex, OpenCode, Zed, or another agent? See the [installation guide](docs/installation.md) for per-agent setup. ### Bash / AGENTS.md @@ -83,7 +84,7 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac -Once installed, run `semble savings` to see how many tokens Semble has saved you. Note that for sub-agent support in Claude Code or Codex, you need the full [Bash / AGENTS.md](#bash-agentsmd) setup below. +Once installed, run `semble savings` to see how many tokens Semble has saved you. Note that sub-agents cannot call MCP tools directly — see [Bash / AGENTS.md](#bash-agentsmd) and `semble init` below.
Updating Semble @@ -102,7 +103,7 @@ uv cache clean semble # for MCP users (restart your MCP client after) - **Accurate**: NDCG@10 of 0.854 on our [benchmarks](#benchmarks), on par with code-specialized transformer models, at a fraction of the size and cost. - **Token-efficient**: returns only the relevant chunks, using [~98% fewer tokens than grep+read](#benchmarks). - **Zero setup**: runs on CPU with no API keys, GPU, or external services required. -- **MCP server**: works with Claude Code, Cursor, Codex, OpenCode, and any other MCP-compatible agent. +- **MCP server**: works with Claude Code, Gemini CLI, Cursor, Codex, OpenCode, Zed, and any other MCP-compatible agent. - **Local and remote**: pass a local path or a git URL. ## MCP Server @@ -118,39 +119,7 @@ Semble can run as an MCP server so agents can search any codebase directly. Repo claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` -#### Codex -Add to `~/.codex/config.toml`: -```toml -[mcp_servers.semble] -command = "uvx" -args = ["--from", "semble[mcp]", "semble"] -``` - -#### OpenCode -Add to `~/.opencode/config.json`: -```json -{ - "mcp": { - "semble": { - "type": "local", - "command": ["uvx", "--from", "semble[mcp]", "semble"] - } - } -} -``` - -#### Cursor -Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): -```json -{ - "mcpServers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"] - } - } -} -``` +For Gemini CLI, Cursor, Codex, OpenCode, Zed, and others, see the [installation guide](docs/installation.md). ### Tools @@ -164,9 +133,9 @@ Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): ## Bash / AGENTS.md -An alternative to MCP is to invoke Semble via Bash. For Claude Code and Codex CLI, this is the only option for sub-agents, which cannot call MCP tools directly, though it can also be used alongside MCP for the top-level agent. +An alternative to MCP is to invoke Semble via Bash. Sub-agents cannot call MCP tools directly, so this is the only option for sub-agent support; it can also be used alongside MCP for the top-level agent. -To add Bash support, append the following to your `AGENTS.md` or `CLAUDE.md`: +To add Bash support, append the following to your `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalent: ```markdown ## Code Search @@ -197,15 +166,20 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac 4. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. ``` -**Claude Code sub-agent**: Claude Code also supports a dedicated sub-agent. Run this once in your project root: +**Sub-agent support**: Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run once in your project root: ```bash -semble init +semble init # Claude Code (default) +semble init --agent gemini +semble init --agent cursor +semble init --agent opencode +semble init --agent copilot +semble init --agent kiro # or, if semble is not on $PATH: -uvx --from "semble[mcp]" semble init +uvx --from "semble[mcp]" semble init --agent copilot ``` -This writes [`.claude/agents/semble-search.md`](src/semble/agents/semble-search.md). +See the [installation guide](docs/installation.md) for all supported agents and options. ## CLI diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..b7d5475 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,223 @@ +# Installation + +## Install semble + +```bash +pip install semble # with pip +uv tool install semble # with uv (recommended) +``` + +To use semble as an MCP server, install the MCP extras: + +```bash +pip install "semble[mcp]" +uv tool install "semble[mcp]" +``` + +
+Updating semble + +```bash +pip install --upgrade semble # with pip +uv tool upgrade semble # with uv +uv cache clean semble # for MCP users (restart your MCP client after) +``` + +
+ +--- + +## MCP Setup + +The MCP server lets your agent search any codebase directly in natural language. Repos are indexed on demand and cached for the session; local paths are re-indexed automatically on file changes. + +> All MCP setups require [uv](https://docs.astral.sh/uv/getting-started/installation/). + +### Claude Code + +```bash +claude mcp add semble -s user -- uvx --from "semble[mcp]" semble +``` + +### Gemini CLI + +Add to `~/.gemini/settings.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +### Cursor + +Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +### Codex + +Add to `~/.codex/config.toml`: + +```toml +[mcp_servers.semble] +command = "uvx" +args = ["--from", "semble[mcp]", "semble"] +``` + +### OpenCode + +Add to `~/.opencode/config.json`: + +```json +{ + "mcp": { + "semble": { + "type": "local", + "command": ["uvx", "--from", "semble[mcp]", "semble"] + } + } +} +``` + +### Zed + +Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project): + +```json +{ + "context_servers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +### GitHub Copilot CLI + +Add to `~/.copilot/mcp-config.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +### Kiro + +Add to `~/.kiro/settings/mcp.json` (or `.kiro/settings/mcp.json` in your project): + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"], + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### MCP Tools + +| Tool | Description | +|------|-------------| +| `search` | Search a codebase with a natural-language or code query. Pass `repo` as a local path or an `https://` git URL. | +| `find_related` | Given a file path and line number, return chunks semantically similar to the code at that location. | + +--- + +## Sub-agent Setup (`semble init`) + +Sub-agents run in their own context window and cannot call MCP tools directly. Use `semble init` to install a dedicated semble search agent so sub-agents can call semble via Bash instead. + +Run once in your project root: + +```bash +semble init # Claude Code (default) +semble init --agent gemini +semble init --agent cursor +semble init --agent opencode +semble init --agent copilot +semble init --agent kiro + +# if semble is not on $PATH: +uvx --from "semble[mcp]" semble init --agent copilot +``` + +| Agent | File written | Source | +|-------|-------------|--------| +| `claude` | `.claude/agents/semble-search.md` | [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/sub-agents) | +| `gemini` | `.gemini/agents/semble-search.md` | [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/core/subagents.md) | +| `cursor` | `.cursor/agents/semble-search.md` | [Cursor docs](https://cursor.com/docs/subagents) | +| `opencode` | `.opencode/agents/semble-search.md` | [OpenCode docs](https://opencode.ai/docs/agents/) | +| `copilot` | `.github/agents/semble-search.md` | [Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents) | +| `kiro` | `.kiro/agents/semble-search.md` | [Kiro docs](https://kiro.dev/docs/chat/subagents/) | + +Add `--force` to overwrite an existing file. + +**Codex** uses a skills system rather than an agents directory. Add the [Bash / AGENTS.md snippet](#bash--agentsmd) to your `AGENTS.md` instead — Codex sub-agents will pick it up automatically. + +**Zed** is an editor rather than a CLI agent and does not have a sub-agent directory. Use the [MCP setup](#zed) above. + +**Hermes** supports subagents via tool delegation rather than a filesystem agents directory. Use the [Bash / AGENTS.md snippet](#bash--agentsmd) to give Hermes access to semble. + +--- + +## Bash / AGENTS.md + +An alternative to MCP is to call semble via Bash. This works with every agent and is the only option for sub-agents that cannot access MCP tools (Codex, and any other agent that doesn't support `semble init`). + +Install semble, then append the snippet below to your project's `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalent: + +```markdown +## Code Search + +Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: + +​```bash +semble search "authentication flow" ./my-project +semble search "save_pretrained" ./my-project +semble search "save model to disk" ./my-project --top-k 10 +​``` + +Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): + +​```bash +semble find-related src/auth.py 42 ./my-project +​``` + +`path` defaults to the current directory when omitted; git URLs are accepted. + +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. +2. Inspect full files only when the returned chunk is not enough context. +3. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. +4. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. +``` diff --git a/src/semble/cli.py b/src/semble/cli.py index 0f97adb..4702b35 100644 --- a/src/semble/cli.py +++ b/src/semble/cli.py @@ -11,7 +11,15 @@ from semble.stats import format_savings_report from semble.utils import _format_results, _is_git_url, _resolve_chunk -_CLAUDE_FILE_PATH = Path(".claude") / "agents" / "semble-search.md" +_AGENT_PATHS: dict[str, Path] = { + "claude": Path(".claude") / "agents" / "semble-search.md", + "gemini": Path(".gemini") / "agents" / "semble-search.md", + "cursor": Path(".cursor") / "agents" / "semble-search.md", + "opencode": Path(".opencode") / "agents" / "semble-search.md", + "copilot": Path(".github") / "agents" / "semble-search.md", + "kiro": Path(".kiro") / "agents" / "semble-search.md", +} +_DEFAULT_AGENT = "claude" _CLI_DISPATCH_ARGS = frozenset({"search", "find-related", "init", "savings", "-h", "--help"}) @@ -49,9 +57,9 @@ def _mcp_main() -> None: asyncio.run(serve(args.path, ref=args.ref, include_text_files=args.include_text_files)) -def _run_init(*, force: bool = False) -> None: - """Write the Claude Code sub-agent file into the current project.""" - dest = _CLAUDE_FILE_PATH +def _run_init(*, agent: str = _DEFAULT_AGENT, force: bool = False) -> None: + """Write the semble sub-agent file for the given coding agent into the current project.""" + dest = _AGENT_PATHS[agent] if dest.exists() and not force: print(f"{dest} already exists. Run with --force to overwrite.", file=sys.stderr) sys.exit(1) @@ -89,7 +97,14 @@ def _cli_main() -> None: help="Also index non-code text files (.md, .yaml, .json, etc.).", ) - init_p = sub.add_parser("init", help="Write .claude/agents/semble-search.md for Claude Code sub-agent support.") + init_p = sub.add_parser("init", help="Write a semble sub-agent file for your coding agent.") + init_p.add_argument( + "--agent", + "-a", + default=_DEFAULT_AGENT, + choices=list(_AGENT_PATHS), + help=f"Coding agent to set up (default: {_DEFAULT_AGENT}).", + ) init_p.add_argument("--force", action="store_true", help="Overwrite if the file already exists.") savings_p = sub.add_parser("savings", help="Show token savings and usage stats.") @@ -98,7 +113,7 @@ def _cli_main() -> None: args = parser.parse_args() if args.command == "init": - _run_init(force=args.force) + _run_init(agent=args.agent, force=args.force) return if args.command == "savings": From 4c04f800ecdd260c1d4bc5e3c540a64325a3a31c Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:35:40 +0200 Subject: [PATCH 02/13] Update install instructions and semble init --- README.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 187 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 0cbc4eb..2c30cde 100644 --- a/README.md +++ b/README.md @@ -114,12 +114,137 @@ Semble can run as an MCP server so agents can search any codebase directly. Repo > Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) to be installed. -#### Claude Code +
+Claude Code + ```bash claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` -For Gemini CLI, Cursor, Codex, OpenCode, Zed, and others, see the [installation guide](docs/installation.md). +
+ +
+Gemini CLI + +Add to `~/.gemini/settings.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+Cursor + +Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+Codex + +Add to `~/.codex/config.toml`: + +```toml +[mcp_servers.semble] +command = "uvx" +args = ["--from", "semble[mcp]", "semble"] +``` + +
+ +
+OpenCode + +Add to `~/.opencode/config.json`: + +```json +{ + "mcp": { + "semble": { + "type": "local", + "command": ["uvx", "--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+GitHub Copilot CLI + +Add to `~/.copilot/mcp-config.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+Kiro + +Add to `~/.kiro/settings/mcp.json` (or `.kiro/settings/mcp.json` in your project): + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+Zed + +Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project): + +```json +{ + "context_servers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +For more detail see the [installation guide](docs/installation.md). ### Tools @@ -166,20 +291,75 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac 4. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. ``` -**Sub-agent support**: Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run once in your project root: +**Sub-agent support**: Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run `semble init` once in your project root: + +
+Claude Code + +```bash +semble init +``` + +Writes `.claude/agents/semble-search.md`. + +
+ +
+Gemini CLI ```bash -semble init # Claude Code (default) semble init --agent gemini +``` + +Writes `.gemini/agents/semble-search.md`. + +
+ +
+Cursor + +```bash semble init --agent cursor +``` + +Writes `.cursor/agents/semble-search.md`. + +
+ +
+OpenCode + +```bash semble init --agent opencode +``` + +Writes `.opencode/agents/semble-search.md`. + +
+ +
+GitHub Copilot CLI + +```bash semble init --agent copilot +``` + +Writes `.github/agents/semble-search.md`. + +
+ +
+Kiro + +```bash semble init --agent kiro -# or, if semble is not on $PATH: -uvx --from "semble[mcp]" semble init --agent copilot ``` -See the [installation guide](docs/installation.md) for all supported agents and options. +Writes `.kiro/agents/semble-search.md`. + +
+ +If semble is not on `$PATH`, prefix any command with `uvx --from "semble[mcp]"`. See the [installation guide](docs/installation.md) for the full agent table with sources. ## CLI From 23f1abc0e4a5e8683c7bf736d928e600699abd6f Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:44:38 +0200 Subject: [PATCH 03/13] Update install instructions and semble init --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2c30cde..277efd6 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,7 @@ [MCP Server](#mcp-server) • [Bash / AGENTS.md](#bash-agentsmd) • [CLI](#cli) • -[Benchmarks](#benchmarks) • -[Installation guide](docs/installation.md) +[Benchmarks](#benchmarks) @@ -39,7 +38,7 @@ Add Semble to Claude Code (requires [uv](https://docs.astral.sh/uv/getting-start claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` -Using Gemini CLI, Cursor, Codex, OpenCode, Zed, or another agent? See the [installation guide](docs/installation.md) for per-agent setup. +Using Gemini CLI, Cursor, Codex, OpenCode, Zed, or another agent? See [MCP Server](#mcp-server) below for per-agent setup. ### Bash / AGENTS.md @@ -244,7 +243,6 @@ Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project):
-For more detail see the [installation guide](docs/installation.md). ### Tools @@ -359,7 +357,7 @@ Writes `.kiro/agents/semble-search.md`. -If semble is not on `$PATH`, prefix any command with `uvx --from "semble[mcp]"`. See the [installation guide](docs/installation.md) for the full agent table with sources. +If semble is not on `$PATH`, prefix any command with `uvx --from "semble[mcp]"`. ## CLI From e5937fc2f51f9f6a00c633985e2b1861e6e56f1d Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:45:19 +0200 Subject: [PATCH 04/13] Update install instructions and semble init --- docs/installation.md | 223 ------------------------------------------- 1 file changed, 223 deletions(-) delete mode 100644 docs/installation.md diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index b7d5475..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,223 +0,0 @@ -# Installation - -## Install semble - -```bash -pip install semble # with pip -uv tool install semble # with uv (recommended) -``` - -To use semble as an MCP server, install the MCP extras: - -```bash -pip install "semble[mcp]" -uv tool install "semble[mcp]" -``` - -
-Updating semble - -```bash -pip install --upgrade semble # with pip -uv tool upgrade semble # with uv -uv cache clean semble # for MCP users (restart your MCP client after) -``` - -
- ---- - -## MCP Setup - -The MCP server lets your agent search any codebase directly in natural language. Repos are indexed on demand and cached for the session; local paths are re-indexed automatically on file changes. - -> All MCP setups require [uv](https://docs.astral.sh/uv/getting-started/installation/). - -### Claude Code - -```bash -claude mcp add semble -s user -- uvx --from "semble[mcp]" semble -``` - -### Gemini CLI - -Add to `~/.gemini/settings.json`: - -```json -{ - "mcpServers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"] - } - } -} -``` - -### Cursor - -Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): - -```json -{ - "mcpServers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"] - } - } -} -``` - -### Codex - -Add to `~/.codex/config.toml`: - -```toml -[mcp_servers.semble] -command = "uvx" -args = ["--from", "semble[mcp]", "semble"] -``` - -### OpenCode - -Add to `~/.opencode/config.json`: - -```json -{ - "mcp": { - "semble": { - "type": "local", - "command": ["uvx", "--from", "semble[mcp]", "semble"] - } - } -} -``` - -### Zed - -Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project): - -```json -{ - "context_servers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"] - } - } -} -``` - -### GitHub Copilot CLI - -Add to `~/.copilot/mcp-config.json`: - -```json -{ - "mcpServers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"] - } - } -} -``` - -### Kiro - -Add to `~/.kiro/settings/mcp.json` (or `.kiro/settings/mcp.json` in your project): - -```json -{ - "mcpServers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"], - "disabled": false, - "autoApprove": [] - } - } -} -``` - -### MCP Tools - -| Tool | Description | -|------|-------------| -| `search` | Search a codebase with a natural-language or code query. Pass `repo` as a local path or an `https://` git URL. | -| `find_related` | Given a file path and line number, return chunks semantically similar to the code at that location. | - ---- - -## Sub-agent Setup (`semble init`) - -Sub-agents run in their own context window and cannot call MCP tools directly. Use `semble init` to install a dedicated semble search agent so sub-agents can call semble via Bash instead. - -Run once in your project root: - -```bash -semble init # Claude Code (default) -semble init --agent gemini -semble init --agent cursor -semble init --agent opencode -semble init --agent copilot -semble init --agent kiro - -# if semble is not on $PATH: -uvx --from "semble[mcp]" semble init --agent copilot -``` - -| Agent | File written | Source | -|-------|-------------|--------| -| `claude` | `.claude/agents/semble-search.md` | [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/sub-agents) | -| `gemini` | `.gemini/agents/semble-search.md` | [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/core/subagents.md) | -| `cursor` | `.cursor/agents/semble-search.md` | [Cursor docs](https://cursor.com/docs/subagents) | -| `opencode` | `.opencode/agents/semble-search.md` | [OpenCode docs](https://opencode.ai/docs/agents/) | -| `copilot` | `.github/agents/semble-search.md` | [Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents) | -| `kiro` | `.kiro/agents/semble-search.md` | [Kiro docs](https://kiro.dev/docs/chat/subagents/) | - -Add `--force` to overwrite an existing file. - -**Codex** uses a skills system rather than an agents directory. Add the [Bash / AGENTS.md snippet](#bash--agentsmd) to your `AGENTS.md` instead — Codex sub-agents will pick it up automatically. - -**Zed** is an editor rather than a CLI agent and does not have a sub-agent directory. Use the [MCP setup](#zed) above. - -**Hermes** supports subagents via tool delegation rather than a filesystem agents directory. Use the [Bash / AGENTS.md snippet](#bash--agentsmd) to give Hermes access to semble. - ---- - -## Bash / AGENTS.md - -An alternative to MCP is to call semble via Bash. This works with every agent and is the only option for sub-agents that cannot access MCP tools (Codex, and any other agent that doesn't support `semble init`). - -Install semble, then append the snippet below to your project's `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalent: - -```markdown -## Code Search - -Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: - -​```bash -semble search "authentication flow" ./my-project -semble search "save_pretrained" ./my-project -semble search "save model to disk" ./my-project --top-k 10 -​``` - -Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): - -​```bash -semble find-related src/auth.py 42 ./my-project -​``` - -`path` defaults to the current directory when omitted; git URLs are accepted. - -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. -2. Inspect full files only when the returned chunk is not enough context. -3. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. -4. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. -``` From f5ea6572af7bb907b8f3eaf18867099dfddf6e9e Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:48:12 +0200 Subject: [PATCH 05/13] Update install instructions and semble init --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 277efd6..631057a 100644 --- a/README.md +++ b/README.md @@ -289,7 +289,9 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac 4. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. ``` -**Sub-agent support**: Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run `semble init` once in your project root: +### Sub-agent setup + +Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run `semble init` once in your project root:
Claude Code From 2a6536d2f414b952a67ca92df02ca347077aa3a8 Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:49:26 +0200 Subject: [PATCH 06/13] Update install instructions and semble init --- README.md | 69 +++++-------------------------------------------------- 1 file changed, 6 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 631057a..faf747e 100644 --- a/README.md +++ b/README.md @@ -293,72 +293,15 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run `semble init` once in your project root: -
-Claude Code - -```bash -semble init -``` - -Writes `.claude/agents/semble-search.md`. - -
- -
-Gemini CLI - -```bash -semble init --agent gemini -``` - -Writes `.gemini/agents/semble-search.md`. - -
- -
-Cursor - ```bash -semble init --agent cursor +semble init # Claude Code → .claude/agents/semble-search.md +semble init --agent gemini # Gemini CLI → .gemini/agents/semble-search.md +semble init --agent cursor # Cursor → .cursor/agents/semble-search.md +semble init --agent opencode # OpenCode → .opencode/agents/semble-search.md +semble init --agent copilot # Copilot CLI → .github/agents/semble-search.md +semble init --agent kiro # Kiro → .kiro/agents/semble-search.md ``` -Writes `.cursor/agents/semble-search.md`. - -
- -
-OpenCode - -```bash -semble init --agent opencode -``` - -Writes `.opencode/agents/semble-search.md`. - -
- -
-GitHub Copilot CLI - -```bash -semble init --agent copilot -``` - -Writes `.github/agents/semble-search.md`. - -
- -
-Kiro - -```bash -semble init --agent kiro -``` - -Writes `.kiro/agents/semble-search.md`. - -
- If semble is not on `$PATH`, prefix any command with `uvx --from "semble[mcp]"`. ## CLI From c207a0030f0c68c27a54833e753ebd043cf656c8 Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:53:22 +0200 Subject: [PATCH 07/13] Update install instructions and semble init --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index faf747e..209b469 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ uv cache clean semble # for MCP users (restart your MCP client after) - **Accurate**: NDCG@10 of 0.854 on our [benchmarks](#benchmarks), on par with code-specialized transformer models, at a fraction of the size and cost. - **Token-efficient**: returns only the relevant chunks, using [~98% fewer tokens than grep+read](#benchmarks). - **Zero setup**: runs on CPU with no API keys, GPU, or external services required. -- **MCP server**: works with Claude Code, Gemini CLI, Cursor, Codex, OpenCode, Zed, and any other MCP-compatible agent. +- **MCP server**: works with Claude Code, Cursor, Codex, OpenCode, VS Code, Windsurf, and any other MCP-compatible agent. - **Local and remote**: pass a local path or a git URL. ## MCP Server @@ -122,24 +122,6 @@ claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
-
-Gemini CLI - -Add to `~/.gemini/settings.json`: - -```json -{ - "mcpServers": { - "semble": { - "command": "uvx", - "args": ["--from", "semble[mcp]", "semble"] - } - } -} -``` - -
-
Cursor @@ -189,6 +171,24 @@ Add to `~/.opencode/config.json`:
+
+VS Code + +Add to `.vscode/mcp.json` in your project (or your user profile's `mcp.json`): + +```json +{ + "servers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+
GitHub Copilot CLI @@ -207,6 +207,42 @@ Add to `~/.copilot/mcp-config.json`:
+
+Windsurf + +Add to `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+Gemini CLI + +Add to `~/.gemini/settings.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+
Kiro From 5ec10efba3a19816f3e058a46b07e682a9e8867c Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 17:58:54 +0200 Subject: [PATCH 08/13] Update install instructions and semble init --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 209b469..0ff53a4 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Add Semble to Claude Code (requires [uv](https://docs.astral.sh/uv/getting-start claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` -Using Gemini CLI, Cursor, Codex, OpenCode, Zed, or another agent? See [MCP Server](#mcp-server) below for per-agent setup. +Using another agent harness? See [MCP Server](#mcp-server) below for per-agent setup. ### Bash / AGENTS.md @@ -83,7 +83,7 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac
-Once installed, run `semble savings` to see how many tokens Semble has saved you. Note that sub-agents cannot call MCP tools directly — see [Bash / AGENTS.md](#bash-agentsmd) and `semble init` below. +Once installed, run `semble savings` to see how many tokens Semble has saved you. Note that sub-agents cannot call MCP tools directly, see [Bash / AGENTS.md](#bash-agentsmd) and [sub-agent setup](#sub-agent-setup) below for details.
Updating Semble @@ -102,7 +102,7 @@ uv cache clean semble # for MCP users (restart your MCP client after) - **Accurate**: NDCG@10 of 0.854 on our [benchmarks](#benchmarks), on par with code-specialized transformer models, at a fraction of the size and cost. - **Token-efficient**: returns only the relevant chunks, using [~98% fewer tokens than grep+read](#benchmarks). - **Zero setup**: runs on CPU with no API keys, GPU, or external services required. -- **MCP server**: works with Claude Code, Cursor, Codex, OpenCode, VS Code, Windsurf, and any other MCP-compatible agent. +- **MCP server**: works with Claude Code, Cursor, Codex, OpenCode, VS Code, and any other MCP-compatible agent. - **Local and remote**: pass a local path or a git URL. ## MCP Server From 1026a549a3507f14ea7fc3da3ec3e096c28ca14d Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 18:00:00 +0200 Subject: [PATCH 09/13] Update install instructions and semble init --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ff53a4..c2d7a1e 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac
-Once installed, run `semble savings` to see how many tokens Semble has saved you. Note that sub-agents cannot call MCP tools directly, see [Bash / AGENTS.md](#bash-agentsmd) and [sub-agent setup](#sub-agent-setup) below for details. +Note that sub-agents cannot call MCP tools directly, see [Bash / AGENTS.md](#bash-agentsmd) and [sub-agent setup](#sub-agent-setup) below for details.
Updating Semble From 76959a8a873d77c7099a59056bb917304e3714dd Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 18:07:00 +0200 Subject: [PATCH 10/13] Update install instructions and semble init --- tests/test_cli.py | 4 +++- uv.lock | 8 ++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/tests/test_cli.py b/tests/test_cli.py index 0520b7a..af4e5ca 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -5,10 +5,12 @@ import pytest -from semble.cli import _CLAUDE_FILE_PATH, _cli_main, _run_init, main +from semble.cli import _AGENT_PATHS, _cli_main, _run_init, main from semble.types import SearchMode, SearchResult from tests.conftest import make_chunk +_CLAUDE_FILE_PATH = _AGENT_PATHS["claude"] + _CLAUDE_AGENT_FILE = files("semble").joinpath("agents/semble-search.md").read_text(encoding="utf-8") diff --git a/uv.lock b/uv.lock index ef3a139..9ce6273 100644 --- a/uv.lock +++ b/uv.lock @@ -10,7 +10,7 @@ resolution-markers = [ [options] exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values. -exclude-newer-span = "P3D" +exclude-newer-span = "P1W" [[package]] name = "annotated-doc" @@ -3238,15 +3238,15 @@ wheels = [ [[package]] name = "sse-starlette" -version = "3.4.4" +version = "3.4.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, { name = "starlette" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f7/2b/58abc2d1fd397e7dde08e947e05c884d8ef2f78d5e2588c17a12d42d6994/sse_starlette-3.4.4.tar.gz", hash = "sha256:07e0fa0460138baf25cdd5fb28683472c3995dc1642225191b3832d62526bcb0", size = 31819, upload-time = "2026-05-12T17:37:17.019Z" } +sdist = { url = "https://files.pythonhosted.org/packages/64/13/3cafb96bceb02949f265bbdf1cbcea2810271ae709e4aa35e980f90c07fd/sse_starlette-3.4.3.tar.gz", hash = "sha256:a7f6d87cf482cf38b911c31075811c7f8b4efbada8ac9d5199a8e239fed513c9", size = 35247, upload-time = "2026-05-11T17:23:41.987Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/dc/67/805710444ea8cc75fbf70b920ed431a560c4bf9c57f7d5a3117213189399/sse_starlette-3.4.4-py3-none-any.whl", hash = "sha256:3f4dd50d8aed2771a091f3a83000323fc3844541c16b4fe585ae2420cc6df973", size = 16514, upload-time = "2026-05-12T17:37:15.601Z" }, + { url = "https://files.pythonhosted.org/packages/fe/a4/c888212b19dd432110d4a78dbc5e6c1bc7476e5fff2f2df2ea9f298b0003/sse_starlette-3.4.3-py3-none-any.whl", hash = "sha256:bf8a90d76192062f01b55095593606bfc7edd0e3ad481339a6e16e7890bc9367", size = 16514, upload-time = "2026-05-11T17:23:40.352Z" }, ] [[package]] From 09678401336871b2f010257486d1032383f71005 Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 18:31:41 +0200 Subject: [PATCH 11/13] Resolve comments, add fun enum --- README.md | 2 +- src/semble/cli.py | 39 ++++++++++++++++++++++++--------------- tests/test_cli.py | 4 ++-- 3 files changed, 27 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index c2d7a1e..d8b4341 100644 --- a/README.md +++ b/README.md @@ -338,7 +338,7 @@ semble init --agent copilot # Copilot CLI → .github/agents/semble-search semble init --agent kiro # Kiro → .kiro/agents/semble-search.md ``` -If semble is not on `$PATH`, prefix any command with `uvx --from "semble[mcp]"`. +If semble is not on `$PATH`, prefix the command with `uvx --from "semble[mcp]"`. ## CLI diff --git a/src/semble/cli.py b/src/semble/cli.py index 4702b35..6d722bc 100644 --- a/src/semble/cli.py +++ b/src/semble/cli.py @@ -1,6 +1,7 @@ import argparse import asyncio import sys +from enum import Enum from importlib.resources import files from importlib.util import find_spec from pathlib import Path @@ -11,15 +12,23 @@ from semble.stats import format_savings_report from semble.utils import _format_results, _is_git_url, _resolve_chunk -_AGENT_PATHS: dict[str, Path] = { - "claude": Path(".claude") / "agents" / "semble-search.md", - "gemini": Path(".gemini") / "agents" / "semble-search.md", - "cursor": Path(".cursor") / "agents" / "semble-search.md", - "opencode": Path(".opencode") / "agents" / "semble-search.md", - "copilot": Path(".github") / "agents" / "semble-search.md", - "kiro": Path(".kiro") / "agents" / "semble-search.md", -} -_DEFAULT_AGENT = "claude" + +class Agent(str, Enum): + CLAUDE = "claude" + COPILOT = "copilot" + CURSOR = "cursor" + GEMINI = "gemini" + KIRO = "kiro" + OPENCODE = "opencode" + + +def _agent_path(agent: Agent) -> Path: + """Return the project-relative path where the semble sub-agent file should be written.""" + base_dir = ".github" if agent is Agent.COPILOT else f".{agent.value}" + return Path(base_dir) / "agents" / "semble-search.md" + + +_DEFAULT_AGENT = Agent.CLAUDE _CLI_DISPATCH_ARGS = frozenset({"search", "find-related", "init", "savings", "-h", "--help"}) @@ -57,9 +66,9 @@ def _mcp_main() -> None: asyncio.run(serve(args.path, ref=args.ref, include_text_files=args.include_text_files)) -def _run_init(*, agent: str = _DEFAULT_AGENT, force: bool = False) -> None: +def _run_init(*, agent: Agent = _DEFAULT_AGENT, force: bool = False) -> None: """Write the semble sub-agent file for the given coding agent into the current project.""" - dest = _AGENT_PATHS[agent] + dest = _agent_path(agent) if dest.exists() and not force: print(f"{dest} already exists. Run with --force to overwrite.", file=sys.stderr) sys.exit(1) @@ -101,9 +110,9 @@ def _cli_main() -> None: init_p.add_argument( "--agent", "-a", - default=_DEFAULT_AGENT, - choices=list(_AGENT_PATHS), - help=f"Coding agent to set up (default: {_DEFAULT_AGENT}).", + default=_DEFAULT_AGENT.value, + choices=[a.value for a in Agent], + help=f"Coding agent to set up (default: {_DEFAULT_AGENT.value}).", ) init_p.add_argument("--force", action="store_true", help="Overwrite if the file already exists.") @@ -113,7 +122,7 @@ def _cli_main() -> None: args = parser.parse_args() if args.command == "init": - _run_init(agent=args.agent, force=args.force) + _run_init(agent=Agent(args.agent), force=args.force) return if args.command == "savings": diff --git a/tests/test_cli.py b/tests/test_cli.py index af4e5ca..76bc1d8 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -5,11 +5,11 @@ import pytest -from semble.cli import _AGENT_PATHS, _cli_main, _run_init, main +from semble.cli import Agent, _agent_path, _cli_main, _run_init, main from semble.types import SearchMode, SearchResult from tests.conftest import make_chunk -_CLAUDE_FILE_PATH = _AGENT_PATHS["claude"] +_CLAUDE_FILE_PATH = _agent_path(Agent.CLAUDE) _CLAUDE_AGENT_FILE = files("semble").joinpath("agents/semble-search.md").read_text(encoding="utf-8") From d9925cbcfac3c5522d63d31df98379d13bfd9d54 Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 18:33:09 +0200 Subject: [PATCH 12/13] Resolve comments, add fun enum --- src/semble/cli.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/semble/cli.py b/src/semble/cli.py index 6d722bc..5d7f886 100644 --- a/src/semble/cli.py +++ b/src/semble/cli.py @@ -22,16 +22,16 @@ class Agent(str, Enum): OPENCODE = "opencode" +_DEFAULT_AGENT = Agent.CLAUDE +_CLI_DISPATCH_ARGS = frozenset({"search", "find-related", "init", "savings", "-h", "--help"}) + + def _agent_path(agent: Agent) -> Path: """Return the project-relative path where the semble sub-agent file should be written.""" base_dir = ".github" if agent is Agent.COPILOT else f".{agent.value}" return Path(base_dir) / "agents" / "semble-search.md" -_DEFAULT_AGENT = Agent.CLAUDE -_CLI_DISPATCH_ARGS = frozenset({"search", "find-related", "init", "savings", "-h", "--help"}) - - def main() -> None: """Entry point for the semble command-line tool.""" if len(sys.argv) > 1 and sys.argv[1] in _CLI_DISPATCH_ARGS: From 78ebedd0214297fb4b433498025faad3541bc794 Mon Sep 17 00:00:00 2001 From: Pringled Date: Tue, 19 May 2026 18:36:41 +0200 Subject: [PATCH 13/13] Bump --- src/semble/version.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/semble/version.py b/src/semble/version.py index 0026b3b..70fb48f 100644 --- a/src/semble/version.py +++ b/src/semble/version.py @@ -1,2 +1,2 @@ -__version_triple__ = (0, 1, 9) +__version_triple__ = (0, 1, 10) __version__ = ".".join(map(str, __version_triple__))