MinishLab/semble: local code search for coding agents, without the grep loop

The token problem semble was built to remove

A coding agent looking for authentication logic usually does this: run grep for a keyword, get a list of files, read several of them in full, and repeat until the right function appears. The README frames the cost of that loop directly, claiming semble uses roughly 99% fewer tokens than grep plus read. The audience is narrow and specific: agent authors and anyone running Claude Code, Cursor, Codex, OpenCode, or another MCP-compatible client against a real repository. The README lists those clients by name. This is not a search product for a human browsing GitHub in a browser tab. It is a retrieval layer that sits between a language model and a filesystem, and every design decision in the README follows from that: CPU only, no API keys, no GPU, no external services, and a return value made of code chunks rather than whole files.

How indexing and retrieval actually work in semble

Semble builds an embedding index over the repository and searches it with a hybrid of semantic and lexical matching; hybrid-search is one of the keywords declared in pyproject.toml, alongside semantic-search and embeddings. The embedding work is delegated to model2vec, which is a hard dependency pinned at >=0.4.0,<0.10, and nearest-neighbour lookup goes through vicinity, pinned at >=0.4.4,<0.5. File filtering is handled by pathspec, which is what lets .gitignore and .sembleignore share gitignore syntax. Parsing support for language grammars comes from a separate package, semble-grammars, pinned at >=0.1.2,<0.2. That split matters operationally: the grammar package can move on its own release cadence without forcing a semble release. The README states that indexing an average repository takes about 500 ms and answering a query about 1 ms, and that a full end-to-end index and search of a codebase completes in under a second. Those are the project's own figures from its benchmark section, not independent measurements. Indexes are built and cached on first run and, per the CLI section, invalidated automatically when files change. The README does not describe how invalidation is detected, whether by mtime, content hash, or something else.

Installing semble and running your first search

The README's fastest path is the interactive installer, which requires uv to be present first. The two commands below install the tool and then start a prompt-driven setup that detects installed coding agents and asks which integrations to enable: an MCP server, instruction text appended to AGENTS.md or CLAUDE.md, or a dedicated semble-search sub-agent.

uv tool install semble
semble install

To reverse whatever the installer wrote into your agent configuration files, the README gives a single command.

semble uninstall

For sandboxed or scripted environments the prompts can be skipped. The example the README gives targets Claude with both the MCP server and the sub-agent, and --yes suppresses the confirmation prompt. The README notes that --agent is required for a fully non-interactive run.

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

If you only want the CLI, no installer is needed. The example below searches a local project and lets semble build and cache the index on first run. A git URL is also accepted in place of the path, in which case the repository is cloned on demand.

semble search "authentication flow" ./my-project
semble search "save model to disk" https://github.com/MinishLab/model2vec

Result volume is controlled with --top-k, and --content switches the corpus between code, docs, config, and all. The README's example for documentation search reads as follows.

semble search "deployment guide" ./my-project --content docs

There is also a related-code lookup that takes a file and a line number, and a snippet-length control where 0 returns only the path and line range.

semble find-related src/auth.py 42 ./my-project
semble search "authentication flow" ./my-project --max-snippet-lines 10

After installation, the README states that semble --version or -V prints the installed version. If the binary is not on $PATH, the README gives uvx --from "semble[mcp]" semble as a substitute in any of the commands above.

The .sembleignore rules are the sharp edge

Semble reads both .gitignore and .sembleignore, merges their patterns, and applies rules recursively, so a .sembleignore inside a subdirectory governs that subtree only. The README gives two directions of use. Exclusion works exactly like gitignore: a generated/ directory pattern or a *.pb.go pattern keeps those files out of the index. Inclusion is the more interesting case. Files with extensions semble does not index by default can be forced in by prefixing the pattern with an exclamation mark, and the README's examples are !*.proto for Protobuf and !*.cob for COBOL. That is a real limitation disguised as a feature. If your repository's important types live in an extension outside the default set, semantic search will silently return nothing for them until someone writes the include rule, and nothing in the README suggests a warning is emitted when a file type is skipped. The README also notes that a set of well-known non-source directories is always skipped regardless of ignore files, naming node_modules/, .venv/, dist/, build/, and __pycache__/ among them. Those defaults are sensible, but they are not configurable through the ignore files, so a vendored dependency under dist/ cannot be indexed without moving it.

Where semble is the wrong tool

Semble returns chunks. When the question is genuinely about the shape of a whole module, or about a control flow that crosses five files, a chunked answer is the wrong shape of answer, and the agent will still need to read files. The README's own savings display makes this visible: it reports a saving ratio per call, which means the ratio is a per-call figure rather than a guarantee about a whole task. There is also the distribution question. The package metadata classifies the project as Development Status 4 - Beta, and the version numbers in the release list (v0.5.4 through v0.5.6) are consistent with that. Beta here is not a formality: the dependency on semble-grammars is pinned below 0.2, so a grammar change is a version bump in a companion package rather than something semble can absorb quietly. Another boundary is offline or air-gapped work. The README states that everything runs on CPU with no API keys, GPU, or external services, which is a point in its favour, but the installer and the package itself still come from PyPI; the README documents no vendored or offline installation path. Finally, the CLI is positioned as a scripting interface, not an interactive one. There is no mention of a persistent shell, a REPL mode, or a watch mode.

Semble against a code-specialized transformer

The obvious alternative is running a code-specialized embedding model, for example through sentence-transformers, which is listed in the benchmark extra in pyproject.toml alongside tiktoken and matplotlib. The README states that semble matches the retrieval quality of a code-specialized transformer, reporting NDCG@10 of 0.854, while indexing about 340x faster and querying about 17x faster. The difference in approach is the model architecture, not the interface. A transformer-based retriever encodes each chunk with a large model, which is where the 340x indexing gap comes from; semble's model2vec dependency produces static embeddings instead. The practical consequence is that the transformer route is the one to pick when you need to reproduce a published retrieval score exactly, or when you are already running GPU infrastructure for other workloads and the marginal cost of another model is near zero. The semble route is the one to pick when the index has to be built on a developer laptop, rebuilt after every branch switch, and shipped with no key management. The README does not claim semble outperforms transformer retrievers on quality, only that it matches them, and the 0.854 figure is the project's own benchmark.

Maintenance cost, licence, and what to check before upgrading

Semble is MIT licensed, with the licence declared both in the repository's LICENSE file and in the license field of pyproject.toml. MIT is permissive: it allows commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is the extent of what the repository states, and it is not legal advice. On maintenance, the last push was on 2026-09-08 and the most recent release, v0.5.6, was tagged on 2026-09-05, so the project is moving on a roughly monthly release cadence at the time of writing. The upgrade path documented in the README is two commands, one for the tool and one for MCP users.

uv tool upgrade semble
uv cache clean semble

The README notes that MCP users should restart their MCP client after the cache clean, which is the step most likely to be forgotten and the one that produces stale-tool confusion. For contributors, the Makefile exposes install, test, lint, typecheck, fix, pre-commit, and a test-no-git variant that runs pytest with tests/test_git.py ignored. The install target runs uv sync --all-extras and then installs pre-commit hooks. Python 3.10 through 3.13 are supported per the classifiers, so the supported interpreter range is not a constraint for most teams. The dependency pins are the real upgrade risk: model2vec below 0.10, vicinity below 0.5, and semble-grammars below 0.2 all sit on minor-version ceilings, so a major bump in any of them is a semble release rather than something you can resolve in your own lockfile.

Editorial conclusion

Adopt semble if you run a coding agent on repositories large enough that grep plus full-file reads dominate your token bill, and if you are willing to accept a beta-stage Python package in your toolchain. Do not adopt it as a general-purpose code search UI for humans, and do not adopt it if your repository depends on file types that the ignore-file rules exclude by default. Verify first that your agent appears in the interactive installer's detection list, that a .sembleignore with !*.proto or the equivalent extension include actually surfaces your generated types, and that the cached index invalidates the way you expect after a branch switch.

Frequently asked questions

Official sources

1. License: MIT
2. MinishLab/semble on GitHub
3. Project website
4. README
5. Releases