CodeGraph: A Local Pre-Indexed Code Graph for Agent Context

What CodeGraph Solves

AI coding agents like Claude Code and Cursor typically discover code structure through grep, glob, and repeated file reads. That process burns tool calls and tokens before the agent can answer a question or make a change. CodeGraph replaces that crawl with a pre-built knowledge graph: every symbol, call edge, and dependency is indexed once, then kept current as files change. The agent asks one question and gets the relevant source, call paths, and blast radius in a single response. This targets developers who use agentic tools on larger codebases where cross-file discovery is a real cost. The README claims a 2026-08 re-measurement showing 44% lower cost and 62% fewer tokens on average across the benchmark set, but that is a vendor benchmark, not an independent test. The project's own framing is precision: the graph gives surgical context instead of file-by-file search.

The Mechanism: A Rust Kernel and an Auto-Syncing Graph

CodeGraph is a CLI with a Rust kernel. The graph is stored locally in a `.codegraph/` directory per project. The key design choice is auto-sync: a file watcher updates the graph on every file change, so the index is never stale. This differs from tools that require a manual re-index after edits. The graph includes structural extraction and cross-file resolution for every supported language, with no per-language setup. The README mentions dynamic-dispatch hops that grep cannot follow, which suggests the graph captures virtual calls or interface implementations that a text search would miss. The agent integration works through an MCP server. Running `codegraph install` wires that server into each agent's configuration, adding instructions and permissions. The graph itself is built by `codegraph init`, which creates the `.codegraph/` directory and builds the full graph in one step. This separation matters: installing the CLI does not index anything, and agent wiring does not build graphs.

Getting It Running: Install, Wire, Init

Installation is a one-liner for macOS, Linux, or Windows. For macOS and Linux, the command is `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh`. Windows uses PowerShell: `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex`. If you have Node.js, you can use `npm i -g @colbymchenry/codegraph` instead. The installer does not change your current shell, so you need a new terminal. Next, run `codegraph install` to detect and configure supported agents: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot. This step only wires the MCP server; it does not index code. Then, inside a project, run `codegraph init` to create the `.codegraph/` directory and build the graph. Auto-sync is enabled by default, so no further commands are needed. Upgrades use `codegraph upgrade`, which detects the install method and updates in place. Uninstall is also a single command, `codegraph uninstall`, which removes agent configs and the CLI, with options like `--keep-cli` and `--target` for selective removal.

Agent Coverage and Configuration

The supported agents list is broad: Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, Kiro, and GitHub Copilot. The README says `codegraph install` auto-configures each, including GitHub Copilot in VS Code, Copilot CLI, and JetBrains IDEs. That coverage is a strength, but it also means the tool depends on the MCP protocol and each agent's configuration format. The README notes that the installer adds instructions and permissions to each agent, which suggests it modifies config files. This is a double-edged sword: convenience versus control. If you have a custom agent setup or a locked-down environment, the installer might not detect it, or it might overwrite settings you care about. For teams with strict config management, this auto-configuration is worth auditing before running.

Limitations and Failure Modes

The most obvious limitation is language support. The README says every language gets the same treatment and points to a Supported Languages section for the per-language list, so check that your language is covered. If your stack uses a niche language or a new framework, the graph may miss symbols or edges, and the auto-sync might not catch everything. Another failure mode is the initial indexing time. Building a full graph for a large repository is not instant. The auto-sync watcher also has a cost: it runs continuously, consuming CPU and memory. On very large monorepos, that overhead could be significant. The README's own cost savings are measured on a harness that blocks the CLI in both arms, which is an artificial condition. In real use, the agent might still do some file reads for context beyond what the graph provides. The tool is also tied to the MCP ecosystem; if an agent does not support MCP or the integration breaks after an agent update, CodeGraph may stop working.

Alternatives and How They Differ

The most direct alternative is to rely on the agent's built-in file search and retrieval. That approach needs no extra tooling but costs more tokens and tool calls, as CodeGraph's benchmark claims. Another alternative is a semantic code search tool like Sourcegraph or a language server protocol (LSP) based indexer. Sourcegraph offers code intelligence and cross-referencing, but it is often server-based and not designed for local agent context. An LSP server, such as clangd for C or rust-analyzer for Rust, provides precise symbol references and definitions, but it is per-language and does not auto-sync into a graph for an agent. CodeGraph's difference is the pre-indexed graph with a unified MCP interface across many agents. The trade-off is that LSPs are battle-tested and language-specific, while CodeGraph is a newer, cross-language abstraction that may miss language-specific nuances. For a single-language project, an LSP might be more precise. For a multi-language repo with several agents, CodeGraph's single graph is more convenient.

Maintenance, Upgrades, and License

CodeGraph is MIT licensed, which means you can use, modify, and redistribute it freely, with no copyleft obligations. The project has a recent release cadence: v1.6.2 from 2026-10-03, v1.6.1 from 2026-09-29, and v1.6.0 from 2026-08-26. That suggests active development, but it also means the API and config format may change between versions. The `codegraph upgrade` command handles updates, and it can pin a specific version with `codegraph upgrade <version>`. For maintenance, the auto-sync reduces manual upkeep, but the watcher itself is a long-running process that could fail silently. The uninstall command leaves `.codegraph/` directories behind unless you run `codegraph uninit`, which is a clean separation. The README also announces a hosted CodeGraph platform that is coming, with early beta access offered. For now, the local tool is self-contained.

Editorial conclusion

Adopt CodeGraph if you use a supported agent on a codebase where cross-file discovery is a bottleneck and you want a 100% local index with no manual re-indexing. Skip it if you need per-language tuning, if your project is tiny where the overhead outweighs gains, or if you cannot tolerate the initial indexing time. Before adopting, verify that your language and framework are in the supported list, confirm the agent integration works with your specific CLI or IDE version, and test the measured cost savings on your own repos, since the 44% and 62% figures come from a specific benchmark harness that may not match your workload. The project's MIT license and active release cadence lower adoption risk, but the auto-sync watcher and MCP server are new components that deserve a trial run on a non-critical project first.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes