CodeGraph: A Local Pre-Indexed Code Graph for Agent Context
Pre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent, fewer tokens, fewer tool calls, 100% local.
At a glance
- What is it?
- CodeGraph builds a persistent, auto-syncing code knowledge graph for AI coding agents, aiming to cut token usage and tool calls. This review examines its mechanism, installation, limits, and fit.
- Who is it for?
- 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.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
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 seven benchmark repos, 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, though the install method hides that. 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. The README does not specify how it handles conflicts with existing MCP servers or custom instructions. The `--target` flag for uninstall implies you can select agents, but the install side likely has a similar scope. 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, but it does not list which languages are supported in the truncated section. The table of contents includes a 'Supported Languages' section, but the content is cut off. That means you cannot assume 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, and the README does not give performance numbers for that step. 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 stops working until you re-run `codegraph install`.
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.0 from 2026-08-26, v1.5.0 from 2026-07-21, and v1.4.1 from 2026-07-10. 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>`. The README mentions verified releases, but the details are truncated. That is a gap: you cannot confirm how releases are verified. 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 project also has a hosted platform in beta, but the README notes it is separate and requires early access. 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.
Community notes