semble

Quickstart • MCP Server • AGENTS.md • CLI • 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. 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 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.

Semble has three complementary setup paths. The recommended setup is using all three (but you can pick and choose based on your needs):

• MCP server: an MCP server for your agent.
• AGENTS.md: an AGENTS.md snippet with instructions for calling Semble via the CLI.
• Sub-agent: a dedicated semble-search sub-agent for harnesses that support it.

MCP

Expose Semble as a native tool via MCP so your agent can call it directly. Add it to Claude Code (requires uv):

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

See MCP Server below for other harnesses (Cursor, Codex, OpenCode, etc.).

AGENTS.md

Add Semble usage instructions to your agent's context so it knows when and how to call the CLI. Install the Semble CLI, then add the snippet below to your AGENTS.md or CLAUDE.md:

uv tool install semble   # Install with uv (recommended)
pip install semble       # Or with pip

## 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
​```

The index is built on first run (and cached for subsequent runs) and invalidated automatically when files change.

Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:

​```bash
semble search "deployment guide" ./my-project --content docs
semble search "database host port" ./my-project --content config
semble search "authentication" ./my-project --content all
​```

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

---

*[GitHub에서 전체 내용 보기](https://github.com/MinishLab/semble)*