What it is
Semble, from MinishLab, is a code search library and MCP server built for coding agents. The agent asks a question such as 'how is authentication handled?' and gets back ranked code snippets instead of grepping and reading whole files. It runs entirely on CPU with no API keys or external services; on first use it downloads a small embedding model from Hugging Face.
The MCP server has two tools: search, which takes a local path or a git URL (or several, to search related repos as one corpus), and find_related, which returns code similar to a given file and line. Under the hood it splits files with tree-sitter, combines a static Model2Vec embedding model with BM25 keyword search, and re-ranks with code-aware signals. Indexes are cached and refreshed as files change.
Version 0.7.0 shipped on 16 October 2026 and the repo has about 6,300 stars. It is MIT licensed and also works as a CLI or Python library.
Install
uvx --from "semble[mcp]" sembleOur review
Semble does one job and keeps the footprint small. Two tools means almost no context overhead, and because the embedding model is static (no transformer runs at query time), the README reports indexing an average repo in about 500 ms and answering queries in about 1 ms on CPU. That makes it practical on a laptop with no GPU, no Ollama install and no cloud embedding key, which is where several rivals ask for more setup.
The headline claims come from MinishLab's own benchmark of about 1,250 queries over 63 repositories in 19 languages: an NDCG@10 (a standard ranking-quality score) of 0.855, level with the 137M-parameter CodeRankEmbed model while indexing 480 times faster, and 96% recall at 2,000 tokens where grep plus file reads needs a full 100,000-token window to reach 85%. The methodology is published in the repo, but we have found no independent replication, so treat the exact figures with care.
It finds relevant code; it does not understand call graphs, types or references the way Serena's language servers or a code graph such as GitNexus do. For 'who calls this?' or a safe rename you still want one of those. Files over 1 MB are skipped by default, and a git URL makes Semble clone a third-party repo whose contents then flow into the agent's context unvetted.
The project is young (the repo dates from April 2026) but releases come every week or two. Its open issues are about plumbing rather than quality: the sub-agents its installer ships call the CLI instead of the MCP server it also registers, and concurrent agent sessions on one repo each start their own server. Neither is hard to fix, and neither touches the retrieval itself.
Where it earns its place
A backend developer using Claude Code on a large Django monolith
Answer 'where is this handled?' without the agent reading whole files
semble install registers the MCP server; the agent calls search with a natural-language query and gets ranked chunks. On MinishLab's benchmark that reaches 96% recall in about 2,000 tokens, against 100,000 for grep plus reads, which shows up directly on a paid model's input bill.
A security team at a fintech that bars sending source code to cloud APIs
Semantic code search under a no-egress policy
Indexing and search run on CPU on the developer's machine; the only network call is a one-off model download into the Hugging Face cache (HF_HOME), which can be done ahead of time. There are no keys to manage and no per-query cost.
A platform engineer working across five microservice repos
Find the endpoint in one service that a client in another calls
Pass several paths or git URLs to search and Semble merges the per-repo indexes, prefixing results with the repo name; find_related jumps from a known file and line to similar code. It finds similar code, not callers, so dependency questions still need a graph tool.
Before you commit
- Setup
- uv tool install semble, then semble install detects Claude Code, Codex and OpenCode and offers the MCP server, an AGENTS.md or CLAUDE.md snippet, or a semble-search sub-agent; manual configs use uvx --from "semble[mcp]" semble. Documented for Claude Code, Cursor, Codex, OpenCode and VS Code; the first search indexes an average repo in about 500 ms, per the README.
- Integrations
- Two read-only tools: search (local path, https git URL or a list of them; content set to code, docs, config or all) and find_related (file plus line number). The same engine is a CLI and a Python library (SembleIndex).
- Data and privacy
- Code stays on the machine; indexes and token-savings stats live in ~/.cache/semble on Linux and are cleared with semble clear. Remote git URLs are cloned on demand, so results from repos you do not control are untrusted input for the agent. No security advisories are published.
- Cost at scale
- Nothing beyond your own CPU: there is no hosted tier, API key or usage fee. The savings land on the model bill, through fewer tokens read per lookup.
- Limits
- Skips files over 1 MB (SEMBLE_MAX_FILE_BYTES changes this) and well-known build directories such as node_modules and dist. Open issues report that shipped sub-agents use the CLI rather than the MCP server and that concurrent sessions on one repo do not share a server.
What's good
- Runs on CPU with no API keys or external services
- Only two read-only tools, so very low context cost
- Searches local paths and remote git repos, several at once
- Published benchmark methodology
What's not
- Benchmarks are self-reported
- Similarity search only; no call graph or reference tracking
- Downloads a model from Hugging Face on first run
- Young project, pre-1.0
Best for
Developers who want their coding agent to find relevant code quickly without sending code to a cloud embedding service.
Alternatives
Semble: common questions
- Is Semble worth it?
- Semantic code search for agents that costs two tool definitions and no API keys; its striking benchmark figures are still the authors' own. We rate it 4.1 out of 5.
- How much does Semble cost?
- Free and open source (MIT). No API keys or paid services needed.
- What are the downsides of Semble?
- Benchmarks are self-reported; similarity search only; no call graph or reference tracking; downloads a model from Hugging Face on first run; young project, pre-1.0.
- Who is Semble best for?
- Developers who want their coding agent to find relevant code quickly without sending code to a cloud embedding service.
- How much does Semble cost for a team or in production?
- Nothing beyond your own CPU: there is no hosted tier, API key or usage fee. The savings land on the model bill, through fewer tokens read per lookup.
- Is Semble safe for company data?
- Code stays on the machine; indexes and token-savings stats live in ~/.cache/semble on Linux and are cleared with semble clear. Remote git URLs are cloned on demand, so results from repos you do not control are untrusted input for the agent. No security advisories are published.
- What are the best Semble alternatives?
- The closest alternatives we have reviewed are Serena, GitNexus, code-review-graph and Context7.
Answers checked Oct 23, 2026.
Make Semble? Show this rating on your site
