Semble Code Search
Fast, snippet-level code retrieval for coding agents with far less context consumption.
The project says retrieval runs locally on CPU without API keys or an external inference service, and it discloses the initial model download, remote-repository cloning, index and savings caches, installer changes to agent configuration, and cache locations. Interactive installation offers integration choices, unattended installation requires an explicit --yes flag, and uninstall plus granular cache-clearing commands provide strong recovery paths. The MIT file, named authors, and citation metadata provide clear source attribution. Deductions apply because there is no dedicated policy for credentials, private source code, or other sensitive files; ignore files provide only indirect protection. Most runtime dependencies have lower bounds without a supplied lockfile or vulnerability-audit evidence, and some release workflow actions use movable tags. Network destinations, retention details, and an exact inventory of installer changes are not fully documented.
The README, package metadata, CI configuration, and supplied BM25 tests support a broadly coherent implementation account. Tests cover the scoring formula, empty queries, removal state, persistence round trips, and rejection of inconsistent saved state. CI declares coverage across three operating systems and several Python versions, with dependencies centrally declared. Deductions apply because the static material does not establish reliability of the complete search pipeline or installer, and the “zero setup” wording sits somewhat awkwardly beside the uv prerequisite and first-use network download. Model and package availability still depends on PyPI, Hugging Face, and network access. Failure-message evidence is mostly limited to tested BM25 ValueErrors, with no demonstrated messages for download, cloning, permission, configuration-write, or MCP failures.
The material clearly addresses agent users, CLI scripts, MCP clients, Python-library integrations, sub-agents, and local or remote repositories. It offers code, documentation, configuration, and combined indexing modes, result and snippet controls, and a custom-model option. The Python 3.10–3.14 and Linux/macOS/Windows CI matrix further supports environment fit. Deductions apply because capability boundaries are not systematically documented, including behavior for binaries, very large repositories, submodules, first-time offline use, and unsupported languages. MCP parameters are reasonably precise, but the actual AGENTS.md guidance, sub-agent trigger rules, and detailed installation document are absent from the supplied evidence, limiting assessment of trigger precision and irrelevant invocation avoidance.
The README has strong organization across quickstart, CLI, MCP, storage, library API, internals, benchmarks, updates, and licensing. Commands, package names, entry points, and environment-variable names are stable across the supplied files. Examples cover primary operations and result fields, while the complete MIT text agrees with package metadata. Deductions apply because the linked detailed installation document is not supplied and there is no substantial FAQ. Known limitations are not collected or explained systematically. setuptools_scm, the version command, and upgrade instructions provide a version path, but no changelog, compatibility policy, or migration guidance is shown. Authors, an issue tracker, and a release workflow identify maintenance channels, but support ownership, security reporting, and maintenance commitments are unspecified; publisher identity remains unknown rather than suspicious.
The output is designed for agent consumption, exposing file paths, line ranges, and focused code snippets with controls for top-k, content type, and snippet length. Natural-language hybrid search and find-related functionality offer clear marginal value over plain grep, and the documentation explains the BM25, static embedding, RRF, and code-aware reranking design. Deductions apply because the approximately 99% token saving, millisecond latency, and quality-comparison claims are project-authored benchmark statements whose underlying data and methodology files are not supplied here. Initial model download, disk caching, indexing, and remote cloning also mean the operational cost is not literally zero.
The main performance figures are connected to a named benchmark section and methodology link, the savings estimate has an explicit formula, and the BM25 tests trace several low-level behavioral claims. Deductions apply because benchmarks/README.md, raw measurements, the full test suite, and coverage results are absent, so the supplied files cannot independently substantiate the 99%, 220x, 17x, or NDCG@10 0.854 claims. Cross-source corroboration is thin because the README and pyproject are principally statements from the same publisher, while the shown tests validate only a narrow BM25 component. The documentation generally separates implementation descriptions, estimates, and benchmark results, but some marketing language generalizes publisher-run measurements without adequately stating applicability limits or uncertainty.
- First use downloads a model from Hugging Face; offline or network-restricted environments should provision a compatible local model and set SEMBLE_MODEL_NAME.
- Indexes may contain private source or credentials. Configure .gitignore/.sembleignore and review cache permissions, retention, and clearing procedures before use.
- Do not treat the approximately 99% token saving, 220x indexing speed, 17x query speed, or NDCG@10 0.854 as independently verified; the underlying benchmark materials were not supplied.
- semble install modifies agent integration configuration. Review the selected targets and retain configuration backups even though semble uninstall is provided.
- Dependencies are not fully pinned by a supplied lockfile; deployments should lock versions, produce an SBOM, and perform vulnerability scanning.
What does this agent do, and when should you use it?
Semble is a local code-search library for coding agents, delivered through a CLI, Python API, MCP server, and installable search sub-agent. It reads a local directory or clones a remote Git repository on demand, uses tree-sitter to create code-aware chunks, and retrieves them with Model2Vec embeddings, BM25, and Reciprocal Rank Fusion. Natural-language or code queries produce focused snippets with file paths and line ranges instead of entire files. Indexing and search run on CPU without API keys, a GPU, or an external inference service, although the default embedding model must be downloaded from Hugging Face on first use unless a compatible local model is supplied. The project's benchmark of roughly 1,250 queries across 63 repositories and 19 languages reports an NDCG@10 of 0.854 and about 99% lower token use than grep+read.
SembleIndex.from_path() reads a local repository, while SembleIndex.from_git() obtains a remote Git repository; content selection can cover code, docs, config, or combinations of them. Semble chunks files with tree-sitter, measures semantic similarity with static Model2Vec embeddings from potion-code-16M-v2, and runs BM25 to match identifiers and API names. It combines both rankings through Reciprocal Rank Fusion, then applies adaptive query weighting, definition boosts, identifier-stem matching, file-coherence boosts, and penalties for tests, compatibility or legacy shims, examples, and .d.ts declarations. search returns chunks exposing file_path, start_line, end_line, and content; find_related retrieves code similar to a specified file and line. Indexes are persisted after the first search and incrementally refreshed from file modification times, while the savings command estimates tokens avoided relative to reading the complete files containing returned chunks.
- A developer using Codex, Claude Code, Cursor, or another MCP client wants an agent to answer implementation questions without repeatedly grepping and opening whole files.
- An engineer onboarding to a large or unfamiliar repository needs concise, path-and-line-referenced results for concepts such as authentication flow or model persistence.
- A team writing development automation needs standalone repository search through semble search where no MCP session is available.
- A Python tooling author wants to embed code, documentation, and configuration retrieval through SembleIndex and follow a result with similarity search.
- A team that cannot use hosted inference APIs can prepare a compatible Model2Vec model locally and perform indexing and querying on CPU.
What are this agent's strengths and limitations?
- The same retrieval engine is available through a CLI, Python API, MCP server, and dedicated sub-agent, covering several coding-agent workflows.
- Its hybrid Model2Vec and BM25 retrieval, followed by definition boosts and code-aware noise penalties, addresses both conceptual questions and exact symbol searches.
- Indexing and querying execute locally on CPU without API credentials, a GPU, or a hosted inference service.
- Cached indexes refresh incrementally as files change, avoiding a complete rebuild during ordinary local MCP sessions.
- The published benchmark reports roughly 500 ms indexing for an average repository, approximately 1 ms queries, and about 99% fewer tokens than grep+read.
- The default configuration requires a first-use download from Hugging Face; a fully offline installation must supply a compatible Model2Vec model through SEMBLE_MODEL_NAME.
- Installation depends on uv, and the selected MCP, instruction-file, or sub-agent integration must be configured for each coding client.
- Retrieval reflects Semble's chunking and ranking policy; tests, examples, legacy or compat paths, and .d.ts files may rank lower even when they matter to a particular investigation.
- The speed, quality, and token-efficiency claims come from the project's own benchmark and estimation method, with no independent production validation supplied.
- Saved indexes, usage statistics, and the Hugging Face model consume local storage; remote-repository search also requires network access and clones repositories on demand.
How do you install or deploy this agent?
A shell and uv are required. Install the package and launch the interactive integration setup:
uv tool install semble
semble installThe installer detects coding agents including Codex, Claude Code, and OpenCode, then offers MCP, CLI instructions in AGENTS.md/CLAUDE.md, and a semble-search sub-agent. An unattended Codex example is:
semble install --agent codex --type mcp subagent --yesThe default setup needs network access on first use to download and cache the embedding model from Hugging Face. For offline runtime, set SEMBLE_MODEL_NAME to a local path containing a Model2Vec-compatible model. Remove installed integrations with semble uninstall.
How do you use this agent?
Search a local repository:
semble search "authentication flow" ./my-projectSearch a remote repository:
semble search "save model to disk" https://github.com/MinishLab/model2vecLimit results or select a different content class:
semble search "save model to disk" ./my-project --top-k 10
semble search "deployment guide" ./my-project --content docs
semble search "authentication flow" ./my-project --max-snippet-lines 10Find code related to a known location:
semble find-related src/auth.py 42 ./my-projectFor library use, create an index with SembleIndex.from_path("./my-project") and call index.search("save model to disk", top_k=3); each result exposes its path, start and end lines, and snippet content. MCP clients can invoke search or find_related with repo set to a local path or an HTTPS Git URL.
How does this agent compare with similar options?
Against grep+read, Semble returns selected snippets rather than reading complete matching files. Its benchmark reports about 99% fewer tokens on average and 97% recall at roughly 2,000 tokens, versus 85% recall for grep+read with a 100,000-token context. Against the 137M-parameter CodeRankEmbed model, the project reports comparable retrieval quality while indexing about 220 times faster and querying about 17 times faster. These figures are all from the project's described benchmark.