Semble

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

Quickstart • CLI • MCP Server • Installation • Benchmarks

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 ~380x faster and querying ~17x 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

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

• Fast: indexes an average repo in ~500 ms and answers queries in ~1 ms, all on CPU.
• Accurate: NDCG@10 of 0.854 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

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