Semble

// Overview

Semble is a code search library built for AI agents rather than for humans reading results in an editor. When an agent explores an unfamiliar codebase with grep and file reads, most of the tokens it burns are lines it did not need. Semble returns the specific chunks that answer the query, which the project measures at roughly 99% fewer tokens than a grep-and-read loop.

It runs entirely on your machine: no API key, no GPU, no external service. Indexing an average repository takes about 500ms and a query answers in about 1ms on CPU, because retrieval combines Model2Vec static embeddings with BM25 lexical matching through reciprocal rank fusion instead of calling a transformer at query time. Chunking is tree-sitter based, so a result is a whole function or class rather than an arbitrary window, and a code-aware reranking pass adds definition boosts, identifier stemming, file coherence and noise penalties.

You can use it three ways: as a CLI, as a Python library, or — most commonly — as an MCP server. `semble install` detects your coding agents and wires it up, exposing a `search` tool for natural-language queries and a `find_related` tool that returns chunks semantically similar to a given file and line.

// What it does

• Indexes an average repo in ~500ms and answers queries in ~1ms, on CPU only — no API key, GPU or external service
• Retrieval combines Model2Vec embeddings with BM25 through reciprocal rank fusion, plus code-aware reranking signals
• Tree-sitter chunking, so results are coherent code units with file path and line range attached
• MCP server compatible with Claude Code, Cursor, Codex, OpenCode and other MCP agents, exposing `search` and `find_related`
• Accepts a local path or a git URL and caches the index automatically
• Respects `.gitignore` and `.sembleignore`; skips files over 1MB unless `SEMBLE_MAX_FILE_BYTES` is raised
• Reports 0.854 NDCG@10 across a 63-repository, 19-language benchmark, matching the 137M-parameter CodeRankEmbed while indexing far faster

// Getting started

Install the CLI, then let the interactive installer wire Semble into whichever coding agents you have. Everything runs locally.

uv tool install semble
semble install

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

semble search "authentication flow" ./my-project
semble search "save model to disk" https://github.com/MinishLab/model2vec
semble search "deployment guide" ./my-project --content docs
semble find-related src/auth.py 42 ./my-project
semble savings

from semble import ContentType, SembleIndex

index = SembleIndex.from_path("./my-project")
results = index.search("save model to disk", top_k=3)
result = results[0]
result.chunk.file_path
result.chunk.start_line
result.chunk.end_line
result.chunk.content

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Cut the token cost of a coding agent exploring an unfamiliar repository, by returning snippets instead of whole files
• Give an agent semantic code search on a machine with no GPU and no outbound API calls
• Find every place that resembles a given function or line, using `find_related`, before a refactor
• Search a public repository by git URL without cloning it first

// How Semble compares

Semble alongside other open-source code indexing & search tools AI/TLDR tracks, ranked by GitHub stars.