Semble：为编程智能体检索代码

Fast and Accurate Code Search for Agents. Uses 99% fewer tokens than grep+read

Fast and Accurate Code Search for Agents Uses ~99% fewer tokens than grep+read Quickstart • CLI • MCP Server • Installation • Benchmarks Semble is a code search library built for agents. It returns the exact code snippets they need instantly, using ~99% fewer tokens than grep+read. Indexing and searching a full codebase end-to-end takes under a second for most repos, matching the retrieval quality of a code-specialized transformer while indexing ~480x faster and querying ~23x faster (see benchmarks). Everything runs on CPU with no API keys, GPU, or external services. Use it as an MCP server, a CLI tool via AGENTS.md, or a dedicated sub-agent, and any coding agent (Claude Code, Cursor, Codex, OpenCode, etc.) gets instant access to any repo. Quickstart 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. The fastest way to get started is the interactive installer. Install uv, then run: uv tool install semble semble install semble install detects installed coding agents such as Claude Code, Codex, and OpenCode, and then lets you choose which integrations to enable: MCP server: lets the agent call Semble directly as a tool. Instructions: adds CLI usage guidance to AGENTS.md / CLAUDE.md. Sub-agent: installs a dedicated semble-search sub-agent. Skill: installs a semble skill plus a one-line pointer to it in AGENTS.md / CLAUDE.md, instead of the full instructions. To undo the setup, run semble uninstall. For manual setup instructions (MCP config per agent, AGENTS.md snippet, sub-agent files), see the installation docs. Updating Semble uv tool upgrade semble # upgrade uv cache clean semble # for MCP users (restart your MCP client after) Unattended install For sandboxed or scripted environments, skip the prompts with --agent and, optionally, --type: semble install --agent claude --type mcp subagent --yes --agent accepts one or more agent ids (e.g. claude, codex, pi); --type accepts mcp, instructions, subagent, skill, or all (default: all but skill); --yes skips the confirmation prompt (requires --agent for a fully non-interactive run). Main Features Fast: indexes an average repo in ~500 ms and answers queries in ~1 ms, all on CPU. Accurate: NDCG@10 of 0.855 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 ~99% fewer tokens than grep+read. Zero setup: runs on CPU with no API keys, GPU, or external services required. MCP server: works with Claude Code, Cursor, Codex, OpenCode, VS Code, and any other MCP-compatible agent. Local and remote: pass a local path or a git URL, or several of them to search related repos together. CLI Semble also ships as a standalone CLI. This is useful in scripts or anywhere you want search results without an MCP session. Indexes are built and cached on first run, and invalidated automatically when files change. # Search a local repo (index is built and cached automatically) semble search "authentication flow" ./my-project # Search a remote repo (cloned on demand) semble search "save model to disk" https://github.com/MinishLab/model2vec # Search several repos at once (results are prefixed with the repo name) semble search "invoice endpoint" ./service-a ./service-b # Limit results semble search "save model to disk" ./my-project --top-k 10 # Search docs/config/everything instead of just code semble search "deployment guide" ./my-project --content docs # or: config, all # Find code similar to a known location semble find-related src/auth.py 42 ./my-project # Show only the first N lines of each result's snippet (0 = path/line range only) semble search "authentication flow" ./my-project --max-snippet-lines 10 --content accepts code (default), docs, config, or all. --format accepts json (default) or text. 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. semble --version (or -V) prints the installed version. Passing several paths or URLs searches them as one corpus, so a query from repo A can find an endpoint defined in repo B. Each index is cached per repo and merged at query time. Result paths are prefixed with the repo name (service-b/api/invoices.py) and the output includes a repos map from prefix to absolute path or URL. Pass the prefixed path to find-related to search across all repos from a known location. Controlling which files are indexed Semble reads .gitignore and .sembleignore files to determine which files to index. Both files use standard gitignore syntax and their patterns are merged. .sembleignore lets you add semble-specific rules without touching .gitignore. Rules are applied recursively, so a .sembleignore in a subdirectory applies to that subtree. Excluding files: add patterns the same way you would in .gitignore: # .sembleignore generated/ # exclude generated dir *.pb.go. # exclude Go protobuf files Including non-default extensions: prefix the extension pattern with ! to force-include files that semble wouldn't index by default: # .sembleignore !*.proto # include Protobuf files !*.cob # include COBOL files Run semble file-types to see which extensions are indexed per content type. Extensions not listed (including data files such as .json and .csv) are not indexed by default and can be force-included with a ! pattern as above. Semble also always skips a set of well-known non-source directories regardless of ignore files (e.g. node_modules/, .venv/, dist/, build/, __pycache__/, and similar). Savings semble savings shows how many tokens semble has saved across all your searches: semble savings Semble Token Savings ════════════════════════════════════════════════════════════════════════ Total saved: ~714.2M tokens (94%) Total calls: 14.3k Efficiency: ███████████████████████░ 94% By Period ───────────────────────────────────────────