semble

What it is and what it does

Semble is a code search engine designed for AI agents and developers. It builds an index of a codebase using embeddings from model2vec, then answers natural-language queries by returning only the relevant code snippets—not full files. The library runs entirely on CPU with no external APIs or GPU required, and caches both indexes and the embedding model locally.

You can use Semble three ways: as an MCP server (for Claude Code, Cursor, Codex, and other agents), as a CLI tool for one-off searches, or as a Python library for programmatic access. It reads .gitignore and .sembleignore to control which files are indexed, and automatically skips well-known non-source directories. The fact sheet indicates indexing takes roughly 500 ms for an average repo and queries return in roughly 1 ms, with token savings estimated at ~99% compared to reading full files.

Use it for:

• Integrate code search into Claude Code, Cursor, or other MCP-compatible agents so they can find relevant snippets without grepping or reading full files.
• Build a CLI tool to search a remote repository (cloned on demand) or local codebase without setting up a full development environment.
• Use as a Python library to add semantic code search to custom tooling, RAG pipelines, or agent workflows.
• Quickly locate code patterns (e.g., 'how is authentication handled?') across unfamiliar codebases during onboarding or code review.
• Track token savings across searches to quantify efficiency gains when using Semble instead of traditional grep-and-read workflows.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Semble is a code search library that indexes and searches codebases using embeddings, returning relevant code snippets in response to natural-language queries with minimal token overhead.

Yes. Semble is actively maintained, has low install friction, carries a permissive MIT license, and solves a real problem for agent-assisted development. It has no known vulnerabilities and supports current Python versions (3.10–3.13). Install it if you work with coding agents or need fast, token-efficient code search; the MCP integration and CLI are both straightforward to set up.

Install

semble on PyPI

pip install semble

uv add semble

poetry add semble

Installing semble

Before you install

Low friction: pure Python wheel with 7 runtime dependencies including model2vec for embeddings and questionary for CLI prompts. Active maintenance—released 2 days ago with 5879 repository stars and continuous commits.

License in practice

MIT License permits unrestricted commercial and private use, modification, and redistribution with only attribution and license-text retention required.

Quickstart

pip install semble

from semble import SembleIndex

index = SembleIndex.from_path("./my-project")
results = index.search("authentication flow")
for result in results:
    print(result)

Requires Python 3.10 or later. On first use, downloads an embedding model from Hugging Face (one-time, requires network access).

Verify before relying

• Whether the embedding model download size and cache footprint are acceptable for resource-constrained environments.
• Performance characteristics when indexing very large codebases (millions of lines) or with many concurrent searches.
• Compatibility and behavior with non-standard or mixed-language repositories.

Package facts

Evidence: semble-0.5.5-py3-none-any.whl

Keywords: code-search, hybrid-search, semantic-search, mcp, agent, rag, embeddings

Tags

More Libraries packages

Further reading