ContextPilot

ContextPilot automatically builds the smallest possible context for AI coding agents.

Instead of dumping your entire repository (or even a keyword-matched subset of it) into an LLM's context window, ContextPilot indexes your codebase once and returns only the handful of functions actually relevant to the task at hand — as an MCP server that Claude Code, Claude Desktop, and other MCP-compatible agents can call directly.

The problem

Every AI coding agent has to answer the same question before it can help you: which part of this codebase actually matters for this task? Feeding it the whole repo wastes tokens, time, and money. Naive keyword search is cheaper but shallow — it finds Login() and LoginForm() easily, but misses verifyPassword(), createJWT(), or isLoggedIn(), because those functions don't share the word "login" even though they're exactly where a login bug probably lives.

Measured on a real 815-file production codebase, searching for the task "user cannot stay logged in after refresh" (a query that never contains the word "login"):

Method	Context sent	Approx. tokens
Entire repository	815 files	~325,000
ContextPilot	5 functions	~960

That's the entire repository's worth of context reduced by over 99.7% — while still surfacing the actual relevant code (isLoggedIn(), getServerUser()) instead of unrelated UI pages, because the match is semantic, not just keyword-based.

How it works

1. Index — ContextPilot scans your project, parses JavaScript and TypeScript with the TypeScript Compiler API, and stores functions/methods with exact character ranges in a local SQLite database along with a semantic embedding of each function (all-MiniLM-L6-v2, run fully locally via @xenova/transformers — no API key, no data leaves your machine).
2. Search — a query like "fix login bug" is embedded and compared against every indexed function using cosine similarity, blended with keyword-overlap scoring for precision on exact name matches.
3. Call graph — while indexing, ContextPilot records caller → callee relationships. Retrieval can add direct callers and callees (or more hops) only when requested.
4. Context — the top matches are returned as a single pasteable blob of real source code, sized to fit a task, not a whole repo.
5. Incremental by default — re-indexing an 800-file project after touching one file stays fast, since unchanged files are skipped via mtime/size checks.

Installation

npm install -g contextpilotmcp

CLI usage

contextpilot index /path/to/project
contextpilot search "fix login bug" -d /path/to/project
contextpilot context "fix login bug" -d /path/to/project   # full source code of top matches
contextpilot context "fix login bug" -d /path/to/project --expand --depth 2
contextpilot benchmark                              # writes benchmark report files

--expand includes both functions called by each top match and functions that call it. --depth controls the maximum number of call-graph hops (default: 1). Expansion is opt-in so normal searches stay as small as possible.

Benchmarking retrieval quality

contextpilot benchmark runs a fixed, self-contained TypeScript corpus with labelled relevant functions. It writes contextpilot-benchmark-report.md and .json in the current directory, comparing Full Repository, Keyword Search, and Hybrid Search on indexing speed, retrieval latency, estimated token reduction, precision@3, and recall@3. Use --output reports/benchmark.md to choose the Markdown report path.

Using it as an MCP server

ContextPilot ships as a Model Context Protocol server, so any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) can call it as a tool during a conversation — no manual copy-pasting of code into the chat.

Claude Desktop — add to your config (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "contextpilot": {
      "command": "npx",
      "args": ["-y", "contextpilotmcp"]
    }
  }
}

Restart Claude Desktop. In a new chat, ask something like:

"Index /path/to/my-project, then find the functions most relevant to fixing the login bug."

Claude will call contextpilot_index and contextpilot_search automatically.

Available tools

Tool	Description
contextpilot_index	Scans a project and builds/updates the function index
contextpilot_search	Returns ranked function matches, optionally with call dependencies
contextpilot_context	Returns full source code of the top matches, optionally with call dependencies

All three tools accept an optional projectPath. If omitted, ContextPilot falls back to the MCP server's current working directory. contextpilot_search and contextpilot_context also accept expandDependencies: true and an optional expansionDepth (default 1).

• Claude Code — since it's typically launched from inside your project directory (cd my-project && claude), the working directory usually is your project, so you can often skip projectPath entirely and just say "index this project" or "find the functions relevant to X."
• Claude Desktop — the MCP server is started from an unrelated working directory, not your project folder. Always pass projectPath explicitly here, e.g. "index /Users/you/projects/my-app, then search for X."

When in doubt, just pass projectPath explicitly — it always works regardless of client.

License

MIT