에이전트용 초고속 코드 검색 라이브러리 Semble

Fast and Accurate Code Search for Agents Uses ~98% fewer tokens than grep+read Quickstart • MCP Server • Bash / AGENTS.md • CLI • Python API • 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 ). Everything runs on CPU with no API keys, GPU, or external services. Run it as an MCP server or call it from the shell via AGENTS.md 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: MCP Add Semble to Claude Code (requires uv ): claude mcp add semble -s user -- uvx --from " semble[mcp] " semble Using another agent harness? See MCP Server for setup instructions for Codex, OpenCode, Cursor, and other MCP clients. Bash / AGENTS.md Install Semble first, then add the code search snippet to your AGENTS.md or CLAUDE.md : 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 instead of, or alongside, MCP. To update Semble, see Updating . Curious how many tokens Semble has saved you? Run semble savings to see. See Savings for details. 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 , 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 . 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. Local and remote : pass a local path or a git URL. MCP Server Semble can run as an MCP server so agents can search any codebase directly. Repos are cloned and indexed on demand, and indexes are cached for the lifetime of the session. Local paths are watched for file changes and re-indexed automatically. Setup Requires uv to be installed. Claude Code claude mcp add semble -s user -- uvx --from " semble[mcp] " semble Codex Add to ~/.codex/config.toml : [ mcp_servers . semble ] command = " uvx " args = [ " --from " , " semble[mcp] " , " semble " ] OpenCode Add to ~/.opencode/config.json : { "mcp" : { "semble" : { "type" : " local " , "command" : [ " uvx " , " --from " , " semble[mcp] " , " semble " ] } } } Cursor Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project): { "mcpServers" : { "semble" : { "command" : " uvx " , "args" : [ " --from " , " semble[mcp] " , " semble " ] } } } Tools Tool Description search Search a codebase with a natural-language or code query. Pass repo as a local directory path or an https:// git URL. 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). To add Bash support, append the following to your AGENTS.md or CLAUDE.md : ## Code Search Use ` semble search ` to find code by describing what it does or naming a symbol/identifier, instead of grep: ​```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. Claude Code sub-agent : Claude Code also supports a dedicated sub-agent. Run this once in your project root: semble init # or, if semble is not on $PATH: uvx --from " semble[mcp] " semble init This writes .claude/agents/semble-search.md . 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. # Search a local repo semble search " authentication flow " ./my-project # Search for a symbol or identifier 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) 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. Savings semble savings shows how many tokens semble has saved across all your searches: semble savings # summary by period semble savings --verbose # also show breakdown by call type Semble Token Savings ════════════════════════════════════════════════════════════════ Period Calls Savings ──────────────────────────────────────────────────────────────── Today 42 [███████████████░] ~58.4k tokens (95%) Last 7 days 287 [██████████████░░] ~312.4k tokens (90%) 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. Stats are stored in ~/.semble/savings.jsonl . Updating To update/upgrade Semble to the latest version: 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 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. from semble import SembleIndex # Index a local directory index = SembleIndex . from_path ( "./my-project" ) # Index a remote git repository index = SembleIndex . from_git ( "https://github.com/MinishLab/model2vec" ) # Search the index with a natural-language or code query results = index . search ( "save model to disk" , top_k = 3 ) # Find code similar to a specific result related = index . find_related ( results [ 0 ], top_k = 3 ) # Each result exposes the matched chunk result = results [ 0 ] result . chunk . file_path # "model2vec/model.py" result . chunk . start_line # 127 result . chunk . end_line # 150 result . chunk . content # "def save_pretrained(self, path: PathLike, ..." How it works Semble splits each file into code-aware chunks using Chonkie , then scores every query against the chunks with two complementary retrievers: static Model2Vec embeddings using the code-specialized potion-code-16M model for semantic similarity, and BM25 for lexical mat