Code Context README

code-context is the retrieval layer under your coding agent: one local index over the whole repo (keyword, semantic, hybrid, and SQL), reached through an MCP server and a CLI, with the index living in plain files inside your repo. Your agent answers questions about the codebase without reading it file by file.

The rule of thumb: the more a question spans the repo, the more this saves, because the answer comes from a ranked index instead of pulling source into context one file at a time.

On your own codebase, ~30-40% fewer tokens and ~50% fewer tool calls (so answers land faster too - aggregation questions run about 2× quicker). The harness is in the repo, so you can reproduce it on your own code.

Try it live (early preview): ask questions about any public GitHub repo at lantern.infino.ai, a demo agent that runs on code-context.

• 🔎 Find code by words or meaning. One ranked pass fuses exact keyword matching with semantic similarity, and every hit carries the code with path:line citations.
• 📊 Ask questions grep can't answer. Search works as a SQL table function, so "which files have the most code about X" is one query: ranked by relevance, tallied by GROUP BY.
• ⚡ Searching in seconds, fresh forever. The keyword index commits before the embedding model even finishes downloading, vectors backfill in the background, and edits re-sync incrementally: only changed files re-chunk and re-embed.
• 🔒 Nothing leaves your machine. No accounts, no API keys, no database server, no telemetry. Embedding is a small local model, downloaded once; after that everything works offline.

Built on infino, a fast retrieval engine that runs SQL, full-text search, and vector search over a single copy of your data. Text and numeric data is stored as spec-compliant Parquet, and the same engine handles logs, docs, and agent memory.

_{Claude Code answering questions about a repo through code-context: index it, then ask, and it reaches for search and SQL on its own.}

Quick start

Install the Claude Code plugin - nothing to paste into a config:

/plugin marketplace add infino-ai/code-context
/plugin install code-context@infino-ai

It registers code-context's three tools with alwaysLoad already set, so the agent keeps them in view and reaches for the index directly instead of falling back to plain file search.

Not on Claude Code, or prefer a one-line command? Add it as an MCP server:

claude mcp add-json code-context -s user '{"command":"npx","args":["-y","@infino-ai/code-context","mcp"],"alwaysLoad":true}'

The alwaysLoad flag pins this small tool set so that in a setup with many MCP servers - where clients defer tool definitions behind a tool-search step - the agent doesn't miss the index and fall back to plain file search. (Use either the plugin or this command, not both.)

Then just ask a question about the code. The first search or sql on an unindexed repo builds the index inline and answers on the same call: keyword search is live in seconds, and vectors backfill in the background. (Prefer to kick it off yourself? The reindex tool does the same build on demand.)

CI-tested on Linux x64 (glibc) and macOS arm64; linux-arm64, musl, and Windows-via-WSL are expected to work through the engine's prebuilt bindings but are not CI-covered.

Evaluation

Real agent runs over a codebase-Q&A suite (claude-sonnet-4-6, the same minimal prompt for both lanes), on a repo the model has not memorized - infino, the engine this is built on - because that is the realistic case for your private code. Baseline is stock file tools including Bash; the code-context lane is the same tools plus the MCP server. Measured on three axes:

Aggregation is the structural win - ranked search composed with GROUP BY, which file tools cannot express at any budget - and it roughly halves end-to-end time. These numbers are on a strong model; weaker, cheaper models explore less efficiently, so the savings tend to be larger there. On pinpoint symbol lookup, where a single grep is already cheap, an index matches file tools rather than beating them.

Full methodology and per-question tables are in docs/benchmark.md, with the harness in bench/ so you can run the same lanes on your own repo.

What you get

One index and a deliberately small tool surface for agents:

Three tools is a deliberate design: one way to find, one way to count, one way to stay fresh. Every additional near-duplicate retrieval tool worsens an agent's tool selection, and hybrid search's keyword half already ranks exact identifier terms highly, so a separate lexical tool has no job left.

The SQL move

Search-as-a-table composes with aggregation. Ranked by relevance, tallied by SQL, one engine pass:

SELECT path, SUM(end_line - start_line + 1) AS lines, COUNT(*) AS chunks
FROM bm25_search('chunks', 'content', 'vector index quantization', 300)
GROUP BY path ORDER BY lines DESC LIMIT 15

hybrid_search(...) and vector_search(...) work the same way. The CLI and MCP server embed {{name}} placeholders server-side, so agents never handle raw vectors.

Staged readiness

cx index commits the keyword (BM25) index first. On a ~3,000-chunk repo that takes under a second, so search works before any embedding model even exists on the machine. Vectors backfill in the background with a local model (downloaded once, no key; about two minutes for that same repo), and hybrid/semantic ranking unlocks automatically when they land. If the vector stage fails, keyword search stays live and the index says so honestly.

The default model optimizes quality-per-minute. See docs/embedder-eval.md for how it was chosen.

Your index is just files

Everything lives in .infino/ in your repo root (added to your .gitignore automatically on first index): plain files you can copy, cache in CI, or put on object storage. It's a live index the engine queries in place, not a snapshot you export and pass around.

Setup for agents

code-context is an MCP server over stdio, so any MCP client works. Register it once and the tools (search, sql, reindex) become available to the agent.

/plugin marketplace add infino-ai/code-context
/plugin install code-context@infino-ai

claude mcp add-json code-context -s user '{"command":"npx","args":["-y","@infino-ai/code-context","mcp"],"alwaysLoad":true}'

{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"], "alwaysLoad": true } } }

{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"] } } }

[mcp_servers.code-context]
command = "npx"
args = ["-y", "@infino-ai/code-context", "mcp"]

{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"] } } }

{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"] } } }

Tools: search, sql, reindex (incremental sync: an unchanged repo is a fast no-op, and the server also auto-syncs in the background as queries arrive, so results track your edits without anyone asking).

Multiple repos in one session. Each tool takes an optional path (an absolute repo root). Omit it and the server uses its startup root; set it to target a specific repo when a session spans more than one. One server instance serves them all, each with its own index in its own .infino/ - no restart, no per-repo config.

Configuration

Every search / sql result carries a usage receipt - a terse, local line showing the tokens it returned, the files it spanned, and a running session total (e.g. returned ~1.2k tokens | 4 chunks / 3 files | session ~8.4k over 7 queries). Every figure is a ~ estimate, computed in-process - nothing about your queries or code leaves the machine.

CLI

The same index is reachable from the terminal too, for scripting, CI, or inspecting results yourself. Install the binary, then run any command inside a repo:

npm install -g @infino-ai/code-context

cx index [path]           sync the index (incremental; --full rebuilds, --watch follows edits)
cx search <query>         exact terms + meaning, one ranked pass           (-k hits)
cx sql <statement>        read-only SQL; --embed q="text" fills {{q}}
cx status                 what the index holds, how fresh, vector readiness
cx usage                  ledger of queries run and what each returned  (-n, --all, --clear, --json)
cx mcp                    serve the MCP tools over stdio

cx usage reads the local ledger at .infino/usage.jsonl - every search / sql (from the CLI or the MCP server) appends one line recording the query and a compact summary of what came back (paths and line ranges for search, row count for sql), plus the token figures from the receipt. It's a deterministic, model-independent view of what went through the index - no running server or agent needed to read it back. CX_NO_RECEIPT=1 turns off both the inline receipt and this ledger.

How often does the agent actually reach for it?

cx usage can also show, per session, in how many of your prompts code-context was used - e.g. code-context used in 2 of 3 prompts (2 calls). The MCP server can only count its own calls, not your prompts, so this ratio comes from two Claude Code hooks that keep a local tally (nothing is sent anywhere). Add them to your Claude Code settings (~/.claude/settings.json or a project .claude/settings.json):

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "cx usage --hook" }] }
    ],
    "PostToolUse": [
      { "matcher": "mcp__code-context.*", "hooks": [{ "type": "command", "command": "cx usage --hook" }] }
    ]
  }
}

cx usage --hook reads the event on stdin, updates .infino/prompt-stats.json, and prints nothing. If you run code-context via npx, use npx -y @infino-ai/code-context usage --hook as the command.

What it is, and what it isn't

code-context's lane is ranked content retrieval and content-relevance aggregation: find code by words or meaning, rank whole files by how much they're about a topic, always with path:line receipts. It deliberately does not do structural code intelligence (call-graph tracing, dead-code detection, type resolution). Tools that do are complementary: MCP servers stack, so run both.

Architecture

• Chunking: tree-sitter (WASM, no native compiles) cuts at definition boundaries for TypeScript/JS, Python, Rust, Go, Java, C/C++, Ruby, C#, PHP; Markdown splits at headings; everything else falls back to fixed windows. Every chunk carries path, start_line, end_line, lang, content.
• Index: infino tables in .infino/: BM25 (FTS) and IVF vector indexes over a single copy of the data, queried in-process through the Node binding. No server.
• Embeddings: always local. A small model (chosen by a measured eval) downloaded once; no key, no per-query network, code never leaves the machine. Queries embed with the same model the index was built with, and a mismatch is a clear error, not silently wrong results.
• Freshness: incremental by design. A per-file state map (size/mtime prefilter, then content hash) means a sync re-chunks and re-embeds only the files that changed: on a ~3,000-chunk repo an unchanged tree checks in ~20ms and a one-file edit syncs in ~0.7s with vectors kept current (larger-repo numbers in the benchmark). The MCP server auto-syncs in the background as queries arrive (never blocking a query), cx index is incremental by default (--full to rebuild), and cx index --watch syncs on file events.

Learn more

• Code search for coding agents - the crawl-vs-retrieve model and when an index saves tokens.
• FAQ - what it is, when to use it, local-only guarantees, freshness.
• Tradeoffs - the honest limits.
• Benchmark - measured results, with a harness to reproduce them on your own repo.

License

Apache-2.0