ContextSmith

ContextSmith

Give your coding agent the right code, not more code.

A local context engine for Claude Code, Cursor, Codex and any MCP agent. It indexes your repository into a code graph, hybrid search and git history, and answers every task with the code that matters, packed into a token budget you choose.

▶ Watch the 60-second video : indexing, context packing, live MCP calls and the benchmark.

Coding agents spend their context window on the wrong code. They grep, open whole files, and run out of room before they reach the function that needs the fix, and you pay for every token they read. ContextSmith answers one question as well as possible: given this task and N tokens, what code should the agent read?

92% of real bug fixes had the right file inside a 4,000-token context vs 29% for search + whole files 1.7x more often the exact lines to change are shown 48% vs 29%, same budget 100% local no API keys, no cloud, code never leaves the machine

Measured on 114 Django issues from SWE-bench Lite that no tuning step ever saw. Method and full results .

Quickstart (60 seconds)

pipx install "contextsmith[semantic]"      # or: pip install "contextsmith[semantic]"

cd your-repo ctxsmith index # once; afterwards only changed files are re-read ctxsmith context "Coupons are applied twice at checkout" --budget 4000

Connect it to your agent (the command prints the exact line for your machine):

ctxsmith mcp-config claude    # or: cursor, windsurf, codex

claude mcp add contextsmith -- ctxsmith serve --path /path/to/your-repo

From then on the agent calls get_context itself and gets ranked, budgeted code instead of grepping. Without the [semantic] extra everything still works, using keyword search only.

Who it's for

Developers

• Faster, better agent sessions on big repos. The agent starts from the right functions instead of exploring; fewer wrong edits and "I couldn't find it" loops.
• Understand unfamiliar code. ctxsmith context "where are payment retries handled?" returns the relevant functions with their file and line numbers.
• Change safely. ctxsmith impact charge_card lists everything that calls it, transitively: what a change could break, before you make it.
• Remember the gotchas. ctxsmith note add "never call without the account lock" --symbol charge_card pins a note to the code; it shows up in every future context for that code, for you and for the agent.

Teams and companies

Typical rollout: each developer installs it with pipx, runs ctxsmith index in the repositories they work on, and adds one MCP line to their agent. There is nothing to host. See Using it at a company for CI and offline setups.

Builders of AI tools

ContextSmith is also a Python library. Use it as the retrieval layer of your own agent, review bot or internal assistant:

from contextsmith import Engine

eng = Engine("path/to/repo") eng.index() pack = eng.context("Fix the race when two users book the last seat", budget=6000) prompt = f"{pack.text}\n\nTask: fix the race when two users book the last seat."

Results

The test: take a real GitHub issue from SWE-bench Lite, check the repository out at the issue's own commit (so no future code or history leaks in), give the issue text to the tool, and check whether the code the real fix changed comes back.

Final test on Django: 114 issues that no tuning step ever saw.

The baseline pastes BM25-ranked files whole until the budget runs out, which is what "search the repo and open files" agents do. ContextSmith spends the same tokens on the functions that matter and outlines of the rest, so the right file almost always makes it in.

All strategies and ablations

Full numbers: bench/results-django/summary.md.

What the ablations say, including what didn't work:

• Embeddings earn their place: adding them to the lexical ranker lifts top-5 from 79% to 85% and exact-line coverage from 42% to 48%.
• The cross-encoder re-rank hurts the top result (52% → 34%) at 8x the latency, so it is off by default and marked experimental. A general web-search re-ranker doesn't understand issue-to-code relevance; a code-trained one is on the roadmap.
• Git commit history is mixed: it helped on the tuning repositories, but on Django removing it *raises* recall@1 by 4 points. It stays on because the default was fixed before the Django run; changing it now would be tuning on the test set.
• At 8,000 tokens whole files catch up on exact lines (49% vs 51%): every Django fix here touches one file, and at that budget it often fits whole.

Method. Weights were chosen by grid search on 89 issues from 8 other repositories (pytest, requests, flask, sphinx, pylint, xarray, astropy, seaborn) with bench/tune.py and bench/tune_pack.py, then frozen before Django was run once. Reproduce it with ctxsmith bench --repos django/django (first run: about two hours on a laptop).

How it works

flowchart LR

subgraph Index["ctxsmith index (incremental)"] TS["tree-sitter 7 languages"] --> SYM["symbols · calls · imports"] SYM --> G["call graph PageRank"] SYM --> FTS["FTS5 BM25 files · symbols · bodies"] SYM --> EMB["ONNX embeddings symbol summaries"] EMB --> VEC["sqlite-vec cosine index"] GIT["git log"] --> H["commit-message index co-change pairs"] end subgraph Query["get_context(task, budget)"] Q["task text"] --> S1["file BM25"] & S2["semantic kNN"] & S3["paths in task"] & S4["history BM25"] S1 & S2 & S3 & S4 --> RRF["reciprocal-rank fusion"] RRF --> KS["knapsack packer value per token"] KS --> OUT["≤ N tokens of code"] end Index -. one SQLite file .-> Query

One SQLite file per repository holds everything: files, symbols, call and import edges, three FTS5 indexes, git statistics, team notes, and the vector index (a vec0 virtual table from sqlite-vec; a numpy fallback runs where SQLite can't load extensions).

Retrieval (RAG). Each signal produces its own ranked list of files; reciprocal-rank fusion combines them, so no single noisy signal dominates:

The weights come from a grid search (bench/tune.py) on 89 SWE-bench Lite issues from 8 repositories and were then checked on Django, which tuning never saw.

What gets embedded, and why. Not whole files and not raw chunks: one short summary per function or class — path, qualified name, signature, first docstring sentence. On a laptop CPU this is ~30x cheaper than embedding bodies, and it is what identifies "which function is this about". Vectors are cached by content hash, so a function that didn't change is never embedded twice — across re-indexes and across git checkouts. Test files are skipped.

Experimental re-rank. ctxsmith context --rerank re-scores the top 20 files with a cross-encoder (ms-marco-MiniLM-L-6-v2). It is off by default because the benchmark shows it hurts (see Results).

Packing. Candidates are function bodies (matched by name, docstring and body text), class outlines and file outlines. A greedy knapsack takes the best value per token, discounts repeats from one file, and enforces the budget on the final rendered text, so the answer is never over budget.

Always fresh. Re-indexing compares file size and mtime before reading anything and only re-parses and re-embeds what changed; checking an unchanged 2,800-file repository takes about half a s