CodeGraph: The Local Knowledge Graph for AI Coding Agents

AI coding agents are getting better at writing code, but repository discovery remains a stubborn bottleneck. A typical agent still starts with broad searches, opens files one by one, reconstructs call paths, and spends a large share of its context window learning architecture that the project already knows. CodeGraph takes a different approach: build a local, pre-indexed knowledge graph of symbols, dependencies, and call edges, then expose surgical context through an MCP server.

The project, maintained at colbymchenry/codegraph, is designed for Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent, Gemini CLI, Antigravity, Kiro, and GitHub Copilot. Its central promise is not simply “more context.” It is more precise context, delivered with fewer exploratory tool calls.

Why repository discovery is expensive for agents

When a developer asks an agent to explain an authentication flow or change a shared service, the model has to answer two separate questions:

1. Which files and symbols are relevant?
2. What should be changed without breaking callers, routes, tests, or business logic?

Without structural indexing, the agent approximates the answer with grep, glob, directory listings, and file reads. That process is flexible, but it is also repetitive. Dynamic dispatch, re-exports, framework routes, and cross-language boundaries can make text search particularly noisy.

CodeGraph moves this work into an indexing stage. Its README describes a graph containing symbols, call edges, dependencies, and cross-file relationships. An agent can ask for relevant source, call paths, and the blast radius of a change rather than crawling the repository from scratch.

This is an important distinction for production teams: the value is not that the model sees the entire codebase. The value is that it receives the smallest useful slice with structural relationships intact.

How the workflow works

The setup has three stages. First, install the CLI with the project’s shell installer or npm package. The bundled runtime means developers do not need Node.js for the standalone installation, and the project also provides a Windows PowerShell installer.

Second, run codegraph install. The installer detects supported agents and wires the CodeGraph MCP server into their configurations. Installing the CLI and connecting an agent are separate steps, which is a useful operational boundary: a developer can have the binary available without automatically changing every agent configuration.

Third, run codegraph init inside a project. This creates a local .codegraph/ directory and builds the graph. Auto-sync is enabled by default, so the index watches file changes and updates as the code evolves.

That local-first design matters. Source code and the generated index remain on the developer’s machine rather than being sent to a hosted indexing service. Teams with strict repository policies can inspect the project, control the installation, and remove the agent integration with codegraph uninstall if needed.

The benchmark claim—and how to read it

The repository reports a benchmark re-measured on August 5, 2026, using Claude Opus 4.8 across seven open-source repositories in seven languages. The headline aggregate is 88% fewer tool calls, 53% faster completion, 62% fewer tokens, and 44% lower cost for the tested architecture questions. The README says the harness blocked the CodeGraph CLI in both arms to reduce contamination risk.

The per-repository table is more useful than the headline. On VS Code, the indexed agent used a median of two tool calls versus 28 without the graph, with 77% fewer tokens and 71% lower cost. On Excalidraw, it used two calls versus 43, with 84% fewer tokens and 78% lower cost. On Django, the savings were smaller: 41% fewer tokens and 13% lower cost. The README explains that cost varies with how much discovery the question requires.

These numbers should be treated as project-reported measurements, not a universal guarantee. They test architecture questions, a particular model, a particular build, and a specific harness. A small repository, a narrow question, or an agent already equipped with strong repository maps may show a smaller gain.

There is also a subtle trade-off. CodeGraph says its dense retrieval payload can leave more context resident in a multi-turn session. In the same measurements, residual retrieval context was about 80% higher than with file-by-file exploration. Fewer tokens processed and a larger persistent context footprint can both be true. Teams using smaller context windows should monitor session occupancy rather than optimizing only for the first answer.

CodeGraph versus a conventional RAG index

A conventional code RAG system usually chunks files, embeds them, and retrieves semantically similar passages. That can work well for documentation and natural-language queries, but code architecture is relational. A function’s importance depends on callers, imports, routes, implementations, tests, and sometimes framework conventions.

A graph can represent those relationships directly. Semantic retrieval may tell an agent that two files discuss billing; a call and dependency graph can show which function actually reaches the payment provider. For refactoring, the second answer is usually more actionable.

This does not make embeddings obsolete. A strong production stack can combine graph traversal for structure with semantic search for comments, tickets, and domain language. CodeGraph’s narrower approach is attractive when the main failure mode is not “the model cannot find a similar paragraph,” but “the model cannot reconstruct the repository’s shape quickly enough.”

A practical adoption plan

Start with read-only architecture tasks: explain a request path, identify callers of a public function, or map the likely blast radius of a configuration change. Compare tool calls, latency, token consumption, and answer accuracy against the existing workflow.

Next, use the graph for test planning. Before modifying a shared symbol, ask the agent to identify affected routes, packages, and test suites. Make the agent produce a change plan before granting write access. This keeps the graph as an evidence layer rather than an excuse to remove review gates.

Finally, measure the residual context issue. Long sessions should be tested with the same context window and model used by the team. If dense graph responses remain useful but occupy too much context, teams can adopt shorter sessions, explicit summaries, or targeted exploration queries.

Bottom line

CodeGraph is part of a broader shift in AI development tooling: agents are moving from generic file search toward specialized infrastructure for context efficiency. Its strongest idea is simple—precompute code structure locally, then let the agent retrieve relationships instead of rediscovering them.

The reported benchmarks are promising, especially for large, cross-file codebases. The right evaluation is not whether every repository becomes 44% cheaper. It is whether the tool reduces discovery work without hiding important context, weakening review, or creating a stale index. For teams already paying heavily for agent tool calls, a local graph plus MCP is a practical experiment with a clear measurement surface.

Sources: CodeGraph repository, including its installation instructions, supported-agent list, architecture description, and August 2026 benchmark notes.

Related reading

• Harness Engineering for AI Coding Agents: A Practical Guide
• Muse Glimmer: Meta’s 30B Local Agent Deep Dive
• MCP 2026-07-28: Stateless Servers, Routing, and Migration