diff --git a/README.md b/README.md index cd522fac0..588124530 100644 --- a/README.md +++ b/README.md @@ -18,20 +18,19 @@ [Quickstart](#quickstart) • [MCP Server](#mcp-server) • -[Bash / AGENTS.md](#bash-integration) • +[Bash / AGENTS.md](#bash-agentsmd) • [CLI](#cli) • -[Python API](#python-api) • [Benchmarks](#benchmarks) -Semble is a code search library built for agents. It returns the exact code snippets they need instantly, using ~98% fewer tokens than grep+read and cutting latency on every step. Indexing and searching a full codebase end-to-end takes under a second, with ~200x faster indexing and ~10x faster queries than a code-specialized transformer, at 99% of its retrieval quality (see [benchmarks](#benchmarks)). Everything runs on CPU with no API keys, GPU, or external services. Run it as an [MCP server](#mcp-server) or call it from the shell via [AGENTS.md](#bash-integration) and any agent (Claude Code, Cursor, Codex, OpenCode, etc.) gets instant access to any repo. +Semble is a code search library built for agents. It returns the exact code snippets they need instantly, using ~98% fewer tokens than grep+read. Indexing and searching a full codebase end-to-end takes under a second, with ~200x faster indexing and ~10x faster queries than a code-specialized transformer, at 99% of its retrieval quality (see [benchmarks](#benchmarks)). Everything runs on CPU with no API keys, GPU, or external services. Run it as an [MCP server](#mcp-server) or call it from the shell via [AGENTS.md](#bash-agentsmd) and any agent (Claude Code, Cursor, Codex, OpenCode, etc.) gets instant access to any repo. ## Quickstart -Your agent will automatically use Semble whenever it needs to find code. Instead of grepping with a keyword and reading full files, it queries in natural language (e.g. `"How is authentication handled?"`) and gets back only the relevant context. Semble can be set up as an MCP server or as a bash tool: +Your agent queries Semble in natural language (e.g. `"How is authentication handled?"`) and gets back only the relevant code snippets, without grepping or reading full files. Set it up as an MCP server or via AGENTS.md: -### MCP +### MCP (Claude Code) Add Semble to Claude Code (requires [uv](https://docs.astral.sh/uv/getting-started/installation/)): @@ -39,30 +38,71 @@ Add Semble to Claude Code (requires [uv](https://docs.astral.sh/uv/getting-start claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` -Using another agent harness? See [MCP Server](#mcp-server) for setup instructions for Codex, OpenCode, Cursor, and other MCP clients. +Using Codex, OpenCode, or Cursor? See [MCP Server](#mcp-server) for setup instructions. ### Bash / AGENTS.md -Install Semble first, then add the [code search snippet](#bash-integration) to your `AGENTS.md` or `CLAUDE.md`: +Install Semble, then add the snippet below to your `AGENTS.md` or `CLAUDE.md`: ```bash pip install semble # Install with pip uv tool install semble # Or install with uv ``` -> Note: for Claude Code or Codex CLI sub-agents, use the [bash integration](#bash-integration) instead of, or alongside, MCP. +
+AGENTS.md / CLAUDE.md snippet -To update Semble, see [Updating](#updating). +```markdown +## Code Search + +Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep: -Curious how many tokens Semble has saved you? Run `semble savings` to see. See [Savings](#savings) for details. +​```bash +semble search "authentication flow" ./my-project +semble search "save_pretrained" ./my-project +semble search "save model to disk" ./my-project --top-k 10 +​``` + +Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): + +​```bash +semble find-related src/auth.py 42 ./my-project +​``` + +`path` defaults to the current directory when omitted; git URLs are accepted. + +If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. + +### Workflow + +1. Start with `semble search` to find relevant chunks. +2. Inspect full files only when the returned chunk is not enough context. +3. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. +4. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. +``` + +
+ +Once installed, run `semble savings` to see how many tokens Semble has saved you. Note that for sub-agent support in Claude Code or Codex, you need the full [Bash / AGENTS.md](#bash-agentsmd) setup below. + +
+Updating Semble + +```bash +pip install --upgrade semble # with pip +uv tool upgrade semble # with uv +uv cache clean semble # for MCP users (restart your MCP client after) +``` + +
## Main Features - **Fast**: indexes an average repo in ~250 ms and answers queries in ~1.5 ms, all on CPU. - **Accurate**: NDCG@10 of 0.854 on our [benchmarks](#benchmarks), on par with code-specialized transformer models, at a fraction of the size and cost. -- **Token-efficient**: returns only the relevant chunks, using [~98% fewer tokens than grep+read](#token-efficiency). +- **Token-efficient**: returns only the relevant chunks, using [~98% fewer tokens than grep+read](#benchmarks). - **Zero setup**: runs on CPU with no API keys, GPU, or external services required. -- **MCP server**: drop-in tool for Claude Code, Cursor, Codex, OpenCode, and any other MCP-compatible agent. +- **MCP server**: works with Claude Code, Cursor, Codex, OpenCode, and any other MCP-compatible agent. - **Local and remote**: pass a local path or a git URL. ## MCP Server @@ -120,9 +160,11 @@ Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project): | `find_related` | Given a file path and line number, return chunks semantically similar to the code at that location. | -## Bash integration + -An alternative to MCP is to invoke Semble via Bash. For Claude Code and Codex CLI, this is the only option for sub-agents, which cannot call MCP tools directly (both lazy-load MCP schemas at the top-level agent only). +## Bash / AGENTS.md + +An alternative to MCP is to invoke Semble via Bash. For Claude Code and Codex CLI, this is the only option for sub-agents, which cannot call MCP tools directly, though it can also be used alongside MCP for the top-level agent. To add Bash support, append the following to your `AGENTS.md` or `CLAUDE.md`: @@ -167,7 +209,7 @@ This writes [`.claude/agents/semble-search.md`](src/semble/agents/semble-search. ## CLI -Semble also ships as a standalone CLI for use outside of MCP. This is useful in scripts or anywhere you want search results without an MCP session. +Semble also ships as a standalone CLI. This is useful in scripts or anywhere you want search results without an MCP session. ```bash # Search a local repo @@ -179,15 +221,17 @@ semble search "save_pretrained" ./my-project # Search a remote repo (cloned on demand) semble search "save model to disk" https://github.com/MinishLab/model2vec -# Find code similar to a known location (file_path and line from a prior search result) +# Limit results +semble search "save model to disk" ./my-project --top-k 10 + +# Find code similar to a known location semble find-related src/auth.py 42 ./my-project ``` -`path` defaults to the current directory when omitted; git URLs are accepted. - -If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. +`path` defaults to the current directory when omitted; git URLs are accepted. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. -### Savings +
+Savings `semble savings` shows how many tokens semble has saved across all your searches: @@ -206,21 +250,14 @@ semble savings --verbose # also show breakdown by call type All time 1.4k [██████████████░░] ~1.2M tokens (89%) ``` -**How savings are calculated:** for each call, semble records the total character count of the unique files containing returned chunks and the character count of the snippets returned. Estimated tokens saved is `(file chars − snippet chars) / 4` (4 chars per token). This is a conservative estimate: the baseline is reading matched files in full, which is how coding agents often explore unfamiliar code. +Savings are calculated as follows: for each call, semble records the total character count of the unique files containing returned chunks and the character count of the snippets returned. Estimated tokens saved is `(file chars − snippet chars) / 4` (4 chars per token). This is a conservative estimate: the baseline is reading matched files in full, which is how coding agents often explore unfamiliar code. Stats are stored in `~/.semble/savings.jsonl`. -### Updating - -To update/upgrade Semble to the latest version: - -```bash -pip install --upgrade semble # with pip -uv tool upgrade semble # with uv -uv cache clean semble # for MCP users (restart your MCP client after) -``` +
-## Python API +
+Library usage Semble can also be used as a Python library for programmatic access, useful when building custom tooling or integrating search directly into your own code. @@ -247,9 +284,24 @@ result.chunk.end_line # 150 result.chunk.content # "def save_pretrained(self, path: PathLike, ..." ``` +
+ +## Benchmarks + +We benchmark quality and speed across ~1,250 queries over 63 repositories in 19 languages (left), and token efficiency against grep+read at equivalent recall levels (right). + + + + + + +
Speed vs qualityToken efficiency: recall vs. retrieved tokens
+ +The quality benchmark (left) scores retrieval quality (NDCG@10) against total latency; semble achieves 99% of the quality of the 137M-parameter [CodeRankEmbed](https://huggingface.co/nomic-ai/CodeRankEmbed) Hybrid while indexing 218x faster. The token efficiency benchmark (right) measures how many tokens each method needs to reach a given recall level; semble uses 98% fewer tokens on average and hits 94% recall at only 2k tokens, while grep+read needs a full 100k context window to reach 85%. See [benchmarks](benchmarks/README.md) for per-language results, ablations, and full methodology. + ## How it works -Semble splits each file into code-aware chunks using [Chonkie](https://github.com/chonkie-inc/chonkie), then scores every query against the chunks with two complementary retrievers: static [Model2Vec](https://github.com/MinishLab/model2vec) embeddings using the code-specialized [potion-code-16M](https://huggingface.co/minishlab/potion-code-16M) model for semantic similarity, and [BM25](https://github.com/xhluca/bm25s) for lexical matches on identifiers and API names. The two score lists are fused with Reciprocal Rank Fusion (RRF). +Semble splits each file into code-aware chunks using [tree-sitter](https://github.com/tree-sitter/py-tree-sitter), then scores every query against the chunks with two complementary retrievers: static [Model2Vec](https://github.com/MinishLab/model2vec) embeddings using the code-specialized [potion-code-16M](https://huggingface.co/minishlab/potion-code-16M) model for semantic similarity, and [BM25](https://github.com/xhluca/bm25s) for lexical matches on identifiers and API names. The two score lists are fused with Reciprocal Rank Fusion (RRF). After fusing, results are reranked with a set of code-aware signals: @@ -266,33 +318,6 @@ After fusing, results are reranked with a set of code-aware signals: Because the embedding model is static with no transformer forward pass at query time, all of this runs in milliseconds on CPU. -## Benchmarks - -We benchmark quality and speed across all methods on ~1,250 queries over 63 repositories in 19 languages. The x-axis is total latency (index + first query); the y-axis is NDCG@10. Marker size reflects model parameter count. - -![Speed vs quality](https://raw.githubusercontent.com/MinishLab/semble/main/assets/images/speed_vs_ndcg_cold.png) - -| Method | NDCG@10 | Index time | Query p50 | -|--------|--------:|-----------:|----------:| -| CodeRankEmbed Hybrid | 0.862 | 57 s | 16 ms | -| **semble** | **0.854** | **263 ms** | **1.5 ms** | -| CodeRankEmbed | 0.765 | 57 s | 16 ms | -| ColGREP | 0.693 | 5.8 s | 124 ms | -| BM25 | 0.673 | 263 ms | 0.02 ms | -| grepai | 0.561 | 35 s | 48 ms | -| probe | 0.387 | — | 207 ms | -| ripgrep | 0.126 | — | 12 ms | - -Semble achieves 99% of the performance of the 137M-parameter [CodeRankEmbed](https://huggingface.co/nomic-ai/CodeRankEmbed) Hybrid, while indexing 218x faster and answering queries 11x faster. See [benchmarks](benchmarks/README.md) for per-language results, ablations, and methodology. - -### Token efficiency - -Agents using grep+read spend most of their context budget on irrelevant code. Semble returns only the chunks that match, keeping token usage low even at high recall. - -![Token efficiency: recall vs. retrieved tokens](https://raw.githubusercontent.com/MinishLab/semble/main/assets/images/token_efficiency.png) - -Semble uses **98% fewer tokens** on average, and reaches 94% recall at a budget of only 2k tokens, while grep+read needs a full 100k context window to reach 85%. See [benchmarks](benchmarks/README.md#token-efficiency) for details. - ## License MIT