semble Documentation

Technical Documentation: MinishLab/semble

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Fast and Accurate Code Search for Agents
_{Uses ~99% fewer tokens than grep+read}

Semble is a code search library built for agents. It returns the exact code snippets they need instantly, using ~99% fewer tokens than grep+read. Indexing and searching a full codebase end-to-end takes under a second for most repos, matching the retrieval quality of a code-specialized transformer while indexing ~480x faster and querying ~23x faster (see benchmarks). Everything runs on CPU with no API keys, GPU, or external services. Use it as an MCP server, a CLI tool via AGENTS.md, or a dedicated sub-agent, and any coding agent (Claude Code, Cursor, Codex, OpenCode, etc.) gets instant access to any repo.

Quickstart Copy Chapter

Your agent queries Semble in natural language (e.g. "How is authentication handled?") and gets back only the relevant code snippets, without grepping or reading full files.

The fastest way to get started is the interactive installer. Install uv, then run:

uv tool install semble
semble install

semble install detects installed coding agents such as Claude Code, Codex, and OpenCode, and then lets you choose which integrations to enable:

• MCP server: lets the agent call Semble directly as a tool.
• Instructions: adds CLI usage guidance to AGENTS.md / CLAUDE.md.
• Sub-agent: installs a dedicated semble-search sub-agent.

To undo the setup, run semble uninstall.

For manual setup instructions (MCP config per agent, AGENTS.md snippet, sub-agent files), see the installation docs.

Updating Semble

uv tool upgrade semble   # upgrade
uv cache clean semble    # for MCP users (restart your MCP client after)

Unattended install

For sandboxed or scripted environments, skip the prompts with --agent and, optionally, --type:

semble install --agent claude --type mcp subagent --yes

--agent accepts one or more agent ids (e.g. claude, codex, pi); --type accepts mcp, instructions, subagent, or all (default: all); --yes skips the confirmation prompt (requires --agent for a fully non-interactive run).

Main Features Copy Chapter

• Fast: indexes an average repo in ~500 ms and answers queries in ~1 ms, all on CPU.
• Accurate: NDCG@10 of 0.855 on our benchmarks, on par with code-specialized transformer models, at a fraction of the size and cost.
• Token-efficient: returns only the relevant chunks, using ~99% fewer tokens than grep+read.
• 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, and any other MCP-compatible agent.
• Local and remote: pass a local path or a git URL, or several of them to search related repos together.

CLI Copy Chapter

Semble also ships as a standalone CLI. This is useful in scripts or anywhere you want search results without an MCP session. Indexes are built and cached on first run, and invalidated automatically when files change.

# Search a local repo (index is built and cached automatically)
semble search "authentication flow" ./my-project

# Search a remote repo (cloned on demand)
semble search "save model to disk" https://github.com/MinishLab/model2vec

# Search several repos at once (results are prefixed with the repo name)
semble search "invoice endpoint" ./service-a ./service-b

# Limit results
semble search "save model to disk" ./my-project --top-k 10

# Search docs/config/everything instead of just code
semble search "deployment guide" ./my-project --content docs   # or: config, all

# Find code similar to a known location
semble find-related src/auth.py 42 ./my-project

# Show only the first N lines of each result's snippet (0 = path/line range only)
semble search "authentication flow" ./my-project --max-snippet-lines 10

--content accepts code (default), docs, config, or all. --format accepts json (default) or text. 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. semble --version (or -V) prints the installed version.

Passing several paths or URLs searches them as one corpus, so a query from repo A can find an endpoint defined in repo B. Each index is cached per repo and merged at query time. Result paths are prefixed with the repo name (service-b/api/invoices.py) and the output includes a repos map from prefix to absolute path or URL. Pass the prefixed path to find-related to search across all repos from a known location.

Controlling which files are indexed

Semble reads .gitignore and .sembleignore files to determine which files to index. Both files use standard gitignore syntax and their patterns are merged. .sembleignore lets you add semble-specific rules without touching .gitignore. Rules are applied recursively, so a .sembleignore in a subdirectory applies to that subtree.

Excluding files: add patterns the same way you would in .gitignore:

# .sembleignore
generated/     # exclude generated dir
*.pb.go.       # exclude Go protobuf files

Including non-default extensions: prefix the extension pattern with ! to force-include files that semble wouldn't index by default:

# .sembleignore
!*.proto       # include Protobuf files
!*.cob         # include COBOL files

Run semble file-types to see which extensions are indexed per content type. Extensions not listed (including data files such as .json and .csv) are not indexed by default and can be force-included with a ! pattern as above.

Semble also always skips a set of well-known non-source directories regardless of ignore files (e.g. node_modules/, .venv/, dist/, build/, __pycache__/, and similar).

Savings

semble savings shows how many tokens semble has saved across all your searches:

semble savings

Semble Token Savings
  ════════════════════════════════════════════════════════════════════════

  Total saved:  ~714.2M tokens  (94%)
  Total calls:  14.3k
  Efficiency:  ███████████████████████░  94%

  By Period
  ────────────────────────────────────────────────────────────────────────
  Period             Calls           Saved  Ratio
  ────────────────────────────────────────────────────────────────────────
  Today                198    ~1.4M tokens  ███████████████████████░  95%
  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%

  By Call Type
  ────────────────────────────────────────────────────────────────────────
  #     Call type            Calls  Share
  ────────────────────────────────────────────────────────────────────────
  1.    search               14.1k  ████████████████    99%
  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
  ════════════════════════════════════════════════════════════════════════

Savings are calculated as follows: for each call, semble records the total character count of the unique files containing returned chunks and the character count of the snippets returned. Estimated tokens saved is (file chars − snippet chars) / 4 (4 chars per token). This is a conservative estimate: the baseline is reading matched files in full, which is how coding agents often explore unfamiliar code.

Storage

By default, your Semble savings statistics and any saved indexes are stored in the OS cache folder (~/Library/Caches/semble/ on macOS, ~/.cache/semble/ on Linux, %LOCALAPPDATA%\semble\Cache\ on Windows). To override this location you can supply an environment variable SEMBLE_CACHE_LOCATION which should be the full path to the target cache location e.g. ~/my-folder/my-caches/semble.

Files larger than 1 MB are skipped during indexing to keep index builds lean. Skipped files are reported as a warning at index time. If you work with large generated or ingested documents, you can raise (or lower) this limit with the SEMBLE_MAX_FILE_BYTES environment variable (in bytes).

On first use, Semble also downloads the embedding model from Hugging Face and caches it in the standard Hugging Face cache (~/.cache/huggingface/ by default, or $HF_HOME if set); this only happens once and requires network access.

Use semble clear to remove cached data: semble clear index (saved indexes), semble clear savings (usage stats), semble clear orphans (indexes for repos no longer present on disk), or semble clear all (everything).

Library usage

Semble can also be used as a Python library for programmatic access, useful when building custom tooling or integrating search directly into your own code.

from semble import ContentType, SembleIndex

# Index a local directory (code only, the default)
index = SembleIndex.from_path("./my-project")

# Index docs and prose (markdown, rst, etc.)
index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

# Index everything (code, docs, and config)
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG])

# Index code and docs together
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# Index a remote git repository
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Merge indexes from several repos into one (chunk paths are prefixed with the repo name)
index = SembleIndex.merge([("./service-a", SembleIndex.from_path("./service-a")), ("./service-b", SembleIndex.from_path("./service-b"))])

# Search the index with a natural-language or code query
results = index.search("save model to disk", top_k=3)

# Find code similar to a specific result
related = index.find_related(results[0], top_k=3)

# Each result exposes the matched chunk
result = results[0]
result.chunk.file_path   # "model2vec/model.py"
result.chunk.start_line  # 127
result.chunk.end_line    # 150
result.chunk.content     # "def save_pretrained(self, path: PathLike, ..."

When many files need indexing, the CLI and MCP server chunk them in 4 worker processes (SEMBLE_INDEX_WORKERS sets the number, 0 turns them off). In the Python API they are off by default. To turn them on, set SEMBLE_INDEX_WORKERS and call Semble from inside an if __name__ == "__main__": block, since each worker re-imports your script.

MCP Server Copy Chapter

Semble runs as an MCP server so agents can search any codebase directly as a native tool call. Repos are indexed on demand and cached; local paths are re-indexed automatically on file changes.

For per-agent setup instructions, see the installation docs.

Benchmarks Copy Chapter

We benchmark quality and speed across ~1,250 queries over 63 repositories in 19 languages (left), and token efficiency against grep+read at equivalent recall levels (right).

The quality benchmark (left) scores retrieval quality (NDCG@10) against total latency; semble matches the quality of the 137M-parameter CodeRankEmbed while indexing 480x faster. The token efficiency benchmark (right) measures how many tokens each method needs to reach a given recall level; semble uses 99% fewer tokens on average and hits 96% recall at only 2k tokens, while grep+read needs a full 100k context window to reach 85%. See benchmarks for per-language results, ablations, and full methodology.

How it works Copy Chapter

Semble splits each file into code-aware chunks using tree-sitter, then scores every query against the chunks with two complementary retrievers: static Model2Vec embeddings using the code-specialized potion-code-16M-v2 model for semantic similarity, and BM25 for lexical matches on identifiers and API names. The two score lists are fused with Reciprocal Rank Fusion (RRF).

After fusing, results are reranked with a set of code-aware signals:

Ranking signals

• Adaptive weighting. Symbol-like queries (Foo::bar, _private, getUserById) get more lexical weight, while natural-language queries stay balanced between semantic and lexical retrievers.
• Definition boosts. A chunk that defines the queried symbol (a class, def, func, etc.) is ranked above chunks that merely reference it.
• Identifier stems. Query tokens are stemmed and matched against identifier stems in a chunk, giving an additional weight to chunks that contain them. For example, querying parse config boosts chunks containing parseConfig, ConfigParser, or config_parser.
• File coherence. When multiple chunks from the same file match the query, the file is boosted so the top result reflects broad file-level relevance rather than a single out-of-context chunk.
• Noise penalties. Test files, compat//legacy/ shims, example code, and .d.ts declaration stubs are down-ranked so canonical implementations surface first.

Because the embedding model is static with no transformer forward pass at query time, all of this runs in milliseconds on CPU.

Indexes are cached to disk automatically on the first search. On subsequent runs, Semble walks the file tree and compares modification times; added, removed, or changed files are reindexed incrementally, without rebuilding the rest of the index. A full rebuild only happens if the indexing settings change (e.g., after a semble upgrade that changes the model, chunking, or cache format). In MCP mode, the index is checked and refreshed automatically as files change, so results stay current across the session.

Using a custom model Copy Section

If you would like to use another model, you can set your SEMBLE_MODEL_NAME environment variable to a local path or Hugging Face repository. This path is read verbatim, and should contain a Model2Vec compatible model. This is particularly useful if you can't access Hugging Face at runtime.

Acknowledgements Copy Chapter

Thanks to Greptile for providing free access to their AI code review platform.

License Copy Chapter

MIT

Citing Copy Chapter

If you use Semble in your research, please cite the following:

@software{minishlab2026semble,
  author       = {{van Dongen}, Thomas and Stephan Tulkens},
  title        = {Semble: Fast and Accurate Code Search for Agents},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19785932},
  url          = {https://github.com/MinishLab/semble},
  license      = {MIT}
}

Overview (`benchmarks/README.md`) Copy Section

Benchmarks

Quality and speed benchmarks for semble.

• Main results
• Token efficiency
• By language
• Ablations
• Dataset
• Methods
• Excluded methods
• Running the benchmarks

Main results Copy Chapter

Quality and speed across all methods.

semble matches the NDCG@10 of the 137M-param CodeRankEmbed while winning index time by ~480x and query latency by ~23x.

NDCG@10 is averaged across all queries. Speed numbers use one repo per language, CPU only: cold-start index time and warm query p50 (median across 5 consecutive runs).

Token efficiency Copy Chapter

Coding agents (Claude Code, OpenCode, etc.) typically find code by running grep on keywords and reading the matched files. We model that workflow and compare it against semble's chunk retrieval across our full benchmark of 1251 queries.

Expected tokens per query Copy Section

For each query: tokens consumed at first relevant hit, or 32k if the method never finds anything. Averaged across all 1251 queries.

Recall at fixed token budgets Copy Section

A relevant file is "covered" once any retrieved unit comes from it.

Methodology

semble returns the top-50 ranked chunks. ripgrep+read splits the query into keywords (dropping stopwords and short words), runs rg --fixed-strings --ignore-case for each keyword, then reads matched files in full ranked by how many distinct keywords they contain. Both methods search the same set of file types and ignored directories. Tokens are counted with cl100k_base via tiktoken. A relevant file is "covered" once any retrieved unit overlaps its annotated span.

By language Copy Chapter

NDCG@10 per language, sorted by semble. CRE = CodeRankEmbed, cbm = codebase-memory-mcp. Best score per row is bolded.

Ablations Copy Chapter

raw returns retrieval scores directly; + ranking feeds them through semble's hybrid ranker.

By query category

Dataset Copy Chapter

~1,250 queries over 63 repositories in 19 languages, grouped into three categories:

Notes

Languages: three repos per language (nine for Python): bash, C, C++, C#, Elixir, Go, Haskell, Java, JavaScript, Kotlin, Lua, PHP, Python, Ruby, Rust, Scala, Swift, TypeScript, Zig. Repos are pinned by revision in repos.json.

How the benchmark was built: queries and ground-truth relevance labels are generated by Claude Sonnet 4.6. The same model is used as LLM-as-judge to verify label quality.

Methods Copy Chapter

• ripgrep: fast regex search over files, included as a raw keyword-match baseline.
• probe: BM25 keyword ranking backed by tree-sitter parse trees. We use its free probe search mode; its probe agent mode (which does query rewriting) needs a paid LLM API key and isn't tested here.
• cs (Code Spelunker): structural BM25 ranker which ranks matches differently in code/comments/strings).
• ColGREP: late-interaction code retrieval built on next-plaid with the LateOn-Code-edge model.
• grepai: semantic search using nomic-embed-text (137M params) via a local Ollama daemon.
• codebase-memory-mcp: code intelligence engine that indexes a repo into a SQLite/graph store. We benchmark its search_graph tool in fast mode, which does BM25 full-text search with structural boosting.
• ck: hybrid regex + semantic search using BAAI/bge-small-en-v1.5.
• zvec-grep: potion-code-16M-v2 static embeddings + BM25. Benchmarked in direct mode.
• CodeRankEmbed: 137M-param transformer embedding model for code retrieval, used for semantic-only dense search.
• semble: this library. potion-code-16M-v2 static embeddings + BM25 + the semble reranking stack.

Excluded methods Copy Chapter

The following tools were considered but not included in the main comparison:

• codanna: symbol-level semantic search with fastembed. Excluded because it does not support Haskell, Bash, Zig, Scala, Elixir, or Ruby (6 of the 19 benchmark languages).
• claude-context: retrieval-augmented code search using OpenAI embeddings and a vector database. Excluded because it requires a paid OpenAI API key and a running vector-DB service.
• GitNexus: knowledge-graph code search (BM25 + local embeddings + RRF). Excluded because it does not support Bash, Elixir, Haskell, Lua, Scala, or Zig (6 of the 19 benchmark languages).
• codegraph: SQLite FTS5 symbol search + graph traversal. Excluded because it does not support Haskell, Bash, Elixir, or Zig (4 of the 19 benchmark languages).
• tgrep: indexed regex search. Excluded
  because its results are nearly identical to ripgrep (0.1255 vs 0.1259 NDCG@10), and
  ripgrep is already fast enough that indexing adds nothing in our benchmarks.

Running the benchmarks Copy Chapter

Repos are pinned in repos.json and cloned into ~/.cache/semble-bench:

uv run python -m benchmarks.sync_repos          # clone / update
uv run python -m benchmarks.sync_repos --check  # verify only

All tools run CPU-only. semble uses minishlab/potion-code-16M-v2; CodeRankEmbed uses nomic-ai/CodeRankEmbed (137M params). The speed benchmark touches one repo per language with a cold-start index and 5 query runs per repo.

semble

uv run python -m benchmarks.run_benchmark
uv run python -m benchmarks.run_benchmark --repo fastapi --repo axios
uv run python -m benchmarks.run_benchmark --language python

Full runs write to benchmarks/results/semble-hybrid-<sha12>.json.

Speed benchmark

uv run python -m benchmarks.speed_benchmark
uv run python -m benchmarks.speed_benchmark --tools semble zvec-grep   # subset of tools
uv run python -m benchmarks.speed_benchmark --repo flask --repo axios  # subset of repos

Writes to benchmarks/results/speed-<sha12>.json.

Ablations

uv run python -m benchmarks.baselines.ablations
uv run python -m benchmarks.baselines.ablations --mode bm25
uv run python -m benchmarks.baselines.ablations --mode semble-semantic

probe

Needs probe on $PATH (npm install @buger/probe).

uv run python -m benchmarks.baselines.probe
uv run python -m benchmarks.baselines.probe --repo fastapi --repo axios

grepai

Needs grepai on $PATH and Ollama running with nomic-embed-text pulled:

ollama pull nomic-embed-text

uv run python -m benchmarks.baselines.grepai
uv run python -m benchmarks.baselines.grepai --repo fastapi --repo axios

Large repos take several minutes to index. Use --timeout <seconds> (default 120) for repos with many files:

uv run python -m benchmarks.baselines.grepai --timeout 1800 --output results.json

The --output flag enables resume mode: already-completed repos are skipped on restart.

cs (Code Spelunker)

Needs cs on $PATH (go install github.com/boyter/cs/v3@latest).

uv run python -m benchmarks.baselines.cs
uv run python -m benchmarks.baselines.cs --repo fastapi --repo axios

codebase-memory-mcp

Needs codebase-memory-mcp on $PATH (uv tool install codebase-memory-mcp, or pip/npm/brew). First run downloads a small platform binary.

uv run python -m benchmarks.baselines.codebase_memory
uv run python -m benchmarks.baselines.codebase_memory --repo fastapi --repo axios

Each repo is indexed under a semble-bench-<repo> project name and deleted again after evaluation, so it doesn't collide with any projects you have indexed for real use.

ck

Needs ck on $PATH (cargo install ck-search or npm install @beaconbay/ck-search). Requires outbound HTTPS to Hugging Face to download its BAAI/bge-small-en-v1.5 embedding model on first run.

uv run python -m benchmarks.baselines.ck
uv run python -m benchmarks.baselines.ck --repo fastapi --repo axios

zvec-grep

Needs zg on $PATH (npm install @zvec/[email protected], requires Node.js 22+). Downloads the potion-code-16m-v2 embedding model on first index. The published numbers were measured with 0.2.1; the runner records the installed version in its results file, and pinning matters because it parses zg's human-readable output.

uv run python -m benchmarks.baselines.zvecgrep
uv run python -m benchmarks.baselines.zvecgrep --repo fastapi --repo axios

ripgrep

Needs rg on $PATH (brew install ripgrep / apt install ripgrep).

uv run python -m benchmarks.baselines.ripgrep
uv run python -m benchmarks.baselines.ripgrep --no-fixed-strings

ColGREP

Needs the colgrep binary on $PATH.

uv run python -m benchmarks.baselines.colgrep
uv run python -m benchmarks.baselines.colgrep --repo fastapi --repo axios

Runs with --code-only everywhere except bash repos (bash-it, bats-core, nvm), which use --no-code-only because ColGREP's code filter excludes .sh/.bash files.

CodeRankEmbed

Requires the benchmark extra (uv sync --extra benchmark).

uv run python -m benchmarks.baselines.coderankembed
uv run python -m benchmarks.baselines.coderankembed --repo fastapi --repo axios

Context-efficiency benchmark

Requires the benchmark extra (uv sync --extra benchmark) and rg on $PATH.

# Recall vs. token-budget across all queries; plots automatically.
uv run python -m benchmarks.token_efficiency recall
uv run python -m benchmarks.token_efficiency recall --repo fastapi

# Regenerate the plot from a saved recall payload.
uv run python -m benchmarks.token_efficiency plot

Writes benchmarks/results/token-efficiency-<sha12>.json and assets/images/token_efficiency.png.

Plots

uv run python -m benchmarks.plot

Writes speed_vs_ndcg_cold.png and speed_vs_ndcg_warm.png to assets/images/.

Installation (`docs/installation.md`) Copy Section

Installation

Recommended: `semble install` Copy Chapter

The interactive installer detects your installed agents and configures any combination of three integrations globally:

• MCP server: exposes Semble as a native tool your agent can call directly.
• AGENTS.md: adds a Semble usage guide to the agent's config file (CLAUDE.md, AGENTS.md, etc.).
• Sub-agent: installs a dedicated semble-search sub-agent for harnesses that support it.

Install the CLI with uv, then run:

uv tool install semble
semble install

To undo:

semble uninstall

Supported agents: Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Codex, VS Code, Windsurf, Zed, Reasonix, Pi, Command Code, Antigravity, ZCode, Grok Build, Qwen Code, Cline, and Kilo Code.

Pi prerequisite: Pi requires the MCP extension to be installed before semble can connect. Run pi install npm:pi-mcp-extension once, then semble install.

Unattended install Copy Section

For sandboxed or scripted environments, pass --agent to skip the interactive prompts:

semble install --agent claude pi --type mcp subagent --yes

• --agent — one or more agent ids (see the list above; use the lowercase form, e.g. claude, codex, pi).
• --type — one or more of mcp, instructions, subagent, or all (default: all). Requires --agent.
• -y/--yes — skip the confirmation prompt. Requires --agent for a fully non-interactive run.

semble uninstall accepts the same flags.

Keeping installed configuration up to date Copy Section

The MCP server config, AGENTS.md/CLAUDE.md instructions, and sub-agent files that semble install writes all pin uvx to the exact semble version you have installed (semble[mcp]==X.Y.Z), so agents keep calling the version the instructions were written for rather than whatever is newest on PyPI. After upgrading (uv tool upgrade semble or pip install --upgrade semble), rerun semble install. This is idempotent and rewrites the pin (and anything else that changed) in place for every agent you select.

Manual setup Copy Chapter

MCP server Copy Section

Requires uv to be installed.

Claude Code

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

OpenCode

Add to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project (or your user profile's mcp.json):

{
  "servers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.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):

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json (or .zed/settings.json in your project):

{
  "context_servers": {
    "semble": {
      "source": "custom",
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Reasonix

Add to ~/.reasonix/config.json (the backwards-compatible MCP config path read by all Reasonix versions):

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Pi

First install the Pi MCP extension (one-time prerequisite):

pi install npm:pi-mcp-extension

Then add to ~/.pi/agent/mcp.json:

{
 "mcpServers": {
 "semble": {
 "command": "uvx",
 "args": ["--from", "semble[mcp]", "semble"]
 }
 }
}

Antigravity

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Command Code

Add to ~/.commandcode/mcp.json:

{
 "mcpServers": {
 "semble": {
 "command": "uvx",
 "args": ["--from", "semble[mcp]", "semble"]
 }
 }
}

Or use the CLI:

cmd mcp add --scope user semble -- uvx --from "semble[mcp]" semble

ZCode

Add to ~/.zcode/cli/config.json under the nested mcp.servers key (or use Settings -> MCP Servers -> Full configuration mode):

{
  "mcp": {
    "servers": {
      "semble": {
        "command": "uvx",
        "args": ["--from", "semble[mcp]", "semble"],
        "type": "stdio"
      }
    }
  }
}

Grok Build

Add to ~/.grok/config.toml:

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

Qwen Code

Add to ~/.qwen/settings.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Cline

Add to ~/.cline/data/settings/cline_mcp_settings.json (shared by the Cline IDE extensions and CLI):

{
  "mcpServers": {
    "semble": {
      "transport": {
        "type": "stdio",
        "command": "uvx",
        "args": ["--from", "semble[mcp]", "semble"]
      }
    }
  }
}

Or use the CLI:

cline mcp add semble --yes -- uvx --from "semble[mcp]" semble

Kilo Code

Add to ~/.config/kilo/kilo.jsonc:

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

The MCP server indexes each requested content selection on first use and caches it separately. Searches default to code; append --content docs, --content config, or --content all to the server command to change that default. The content argument on an individual MCP search overrides it. For example, in Claude Code:

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble --content all

Indexes stay in memory for the lifetime of the server. To free memory while idle, set SEMBLE_MCP_IDLE_TIMEOUT to a number of seconds; indexes unused for that long are dropped from memory and reloaded from the disk cache on the next search.

Instructions (AGENTS.md / CLAUDE.md) Copy Section

Add the snippet below to your AGENTS.md or CLAUDE.md so your agent knows when and how to call the semble CLI:

## 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 --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
​```

The index is built on first run (and cached for subsequent runs) and invalidated automatically when files change.

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:

​```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
​```

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. 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 Copy Section

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).

### Sub-agent

For harnesses that support sub-agents (Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Codex, Reasonix, Pi, Command Code, Antigravity, ZCode, Grok Build, Qwen Code, Kilo Code), you can install a dedicated `semble-search` sub-agent. Copy the appropriate file from [`src/semble/agents/`](../src/semble/agents/) to your agent's agents directory:

> **Pi prerequisite:** Pi sub-agents require the Pi agents extension. Run `pi install npm:pi-agents` once before installing.

| Agent | File | Destination |
|---|---|---|
| Claude Code | `claude.md` | `~/.claude/agents/semble-search.md` |
| Cursor | `cursor.md` | `~/.cursor/agents/semble-search.md` |
| Gemini CLI | `gemini.md` | `~/.gemini/agents/semble-search.md` |
| Kiro | `kiro.md` | `~/.kiro/agents/semble-search.md` |
| OpenCode | `opencode.md` | `~/.config/opencode/agents/semble-search.md` |
| GitHub Copilot | `copilot.md` | `~/.copilot/agents/semble-search.agent.md` |
| Codex | `codex.toml` | `~/.codex/agents/semble-search.toml` |
| Reasonix | `reasonix.md` | `~/.reasonix/skills/semble-search.md` |
| Pi | `pi.md` | `~/.pi/agents/semble-search.md` |
| Command Code | `commandcode.md` | `~/.commandcode/agents/semble-search.md` |
| Antigravity | `antigravity.md` | `~/.gemini/config/skills/semble-search/SKILL.md` |
| ZCode | `zcode.md` | `~/.zcode/agents/semble-search.md` |
| Grok Build | `grok.md` | `~/.grok/agents/semble-search.md` |
| Qwen Code | `qwen.md` | `~/.qwen/agents/semble-search.md` |
| Kilo Code | `kilo.md` | `~/.config/kilo/agents/semble-search.md` |

---

--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~11560 tokens
- Canonical Reference: https://codewiki.google/github.com/MinishLab/semble