CodeGraph: a pre-indexed code graph that MCP agents query instead of grepping

The problem CodeGraph targets: agents that rediscover your codebase on every question

An agent answering "where is this error thrown and what calls it" has no map. It greps, globs, reads files one at a time, and rebuilds call paths and dependencies by hand before it can start the real work. The README frames this as the discovery tax: a pile of tool calls and round-trips that happens before any useful change is made.

CodeGraph's answer is to build the map ahead of time. It extracts every symbol, call edge and dependency into a single graph, then exposes that graph to the agent over MCP, so the agent asks one question and receives the relevant source plus the call paths between symbols and the blast radius of a change. The README calls this "surgical context, not a file-by-file search".

The intended audience is anyone running an agent against a codebase big enough that file crawling is visible in the bill or in the latency: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro and GitHub Copilot are all listed as supported targets. If you are editing a single 200-line script, the graph has nothing to add and the setup cost is pure overhead.

How CodeGraph builds and serves the graph

The pipeline has three stages visible from the repository layout and README. Extraction runs per language and produces symbols and edges. Resolution stitches those per-file results into one cross-file graph, which is the part grep cannot do: the README specifically mentions dynamic-dispatch hops that a text search cannot follow. Storage lands in a local .codegraph/ directory inside the project, created by codegraph init.

Serving happens through an MCP server that the installer wires into each agent. The agent calls CodeGraph tools instead of file-reading tools, and gets back source plus relationships. The README lists a separate MCP Tools section and a CLI Reference section, so the two surfaces are distinct: the CLI is for humans setting up and maintaining the index, MCP is for the agent at query time.

The kernel is written in Rust, per the README's "Kernel powered by Rust" line, while package.json shows a TypeScript package (@colbymchenry/codegraph) with a dist/bin/codegraph.js entry point and a build:kernel script that shells out to scripts/build-kernel.sh. So the shipped artifact is a Node-facing CLI wrapping a Rust kernel, and the npm package bundles its own runtime rather than compiling native code at install time.

The fourth stage is the one people underestimate: a file watcher. Auto-sync is on by default, and the README states the graph updates on every file change, including while the agent itself is editing. That is a background process per project, running for as long as you are working.

Installing CodeGraph and running a first index

The README offers two install paths. The shell installer needs no Node.js and fetches the build for your OS. On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

On Windows, the PowerShell equivalent is:

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

The README warns that the installer puts codegraph on your PATH but does not modify your current shell, so open a new terminal before the next step. If you already have Node, the npm route is npm i -g @colbymchenry/codegraph.

Installing the CLI does not connect it to anything. That is a separate command, and the README is explicit that step 1 alone leaves your agent unwired:

codegraph install

This detects the agents you have and writes CodeGraph's MCP server configuration into each one. It does not index code. Indexing is per project:

cd your-project
codegraph init

After init, .codegraph/ exists in the project and the graph is built. Auto-sync takes over from there, so there is no re-run step. Upgrades go through codegraph upgrade, which detects whether you installed via bundle, npm or npx and updates in place; codegraph upgrade --check reports whether an update exists, and codegraph upgrade <version> pins one.

Removal is worth reading before you install, not after. codegraph uninstall strips CodeGraph's MCP server config, instructions and permissions from every agent it configured, and shows you the installs it found before deleting anything. --keep-cli removes only the agent configuration. Project indexes under .codegraph/ are left alone and are removed per project with codegraph uninit.

The cost and token numbers are the project's own, and the README says so

The README quotes a 2026-08 re-measurement: 44% lower cost and 62% fewer tokens on average across seven benchmark repos, on a harness that blocks the CLI in both arms. It also reports a range, 57% to 78% on questions the file-reading agent needed 28 to 43 tool calls to answer, and near-even results where the agent got there in 7 calls.

Treat that as a claim with a stated method, not as an independent result. The repository contains an evaluation harness (__tests__/evaluation/, with npm run eval and npm run test:eval scripts), which is the right instinct: the numbers are reproducible in principle by anyone willing to run the harness on their own repository. But the benchmark set is the project's own choice of seven repos, and the README's own framing is that cost tracks how much discovery a question demands rather than raw repository size.

That framing is the most useful sentence in the README, because it tells you when not to expect a win. If your questions are "open this file and change this line", the agent was already at 7 tool calls and the graph buys you little. The saving shows up on questions that require tracing a call path across files. Before adopting, pick five real questions from your own backlog and ask which category they fall into.

Where CodeGraph is the wrong tool

Local-only is a feature and a constraint. The README describes CodeGraph as 100% local, and the graph lives in .codegraph/ inside each project. There is no documented shared or hosted index for a team, so every developer builds their own graph and every CI machine would need its own. For a monorepo with heavy branching, that means each clone pays the init cost and runs its own watcher.

The language list is the second boundary. The README has a Supported Languages section and states that every listed language gets full structural extraction and cross-file resolution with no per-language setup, but the list itself is not reproduced in the excerpt available here, so check it against your stack before assuming coverage. A repository dominated by a language outside that list gets a partially useful graph at best.

Third, the watcher is a long-running process per project. The README presents auto-sync as removing a chore, which it does, but it also means an indexer holding file handles and consuming CPU while you work. On a laptop with several large repositories open at once, that is a real cost, and the README does not document a way to pause auto-sync or a resource ceiling for it.

Finally, the hosted platform is described as coming, with early beta access at getcodegraph.com. If your requirement is per-PR analysis of what to test and what could break, the README places that capability in the hosted product, not in the local CLI documented here.

graphify, gitnexus and the file-reading baseline

The searches people run against this project include comparisons with graphify and gitnexus, and the honest answer from what the README documents is that CodeGraph's distinguishing claim is pre-indexing plus continuous sync. The README's contrast is against the agent's default behavior: grep, glob and Read, one file at a time. That is the real alternative, and it is free, already installed, and requires no watcher.

Against that baseline, CodeGraph's advantage is the dynamic-dispatch hops and the pre-computed blast radius, neither of which a text search produces. Its disadvantage is that grep cannot go stale while a graph can, which is why the project leans so hard on auto-sync being enabled by default.

For graphify and gitnexus specifically, the README does not describe their mechanisms, so any comparison would be invented. What can be said is structural: CodeGraph ships a Rust kernel behind a TypeScript CLI, installs via a shell or PowerShell one-liner or npm, and targets nine named agents through MCP. If a competing tool indexes the same repository the same way, the deciding factors become language coverage, whether the index is shared or local, and whether the tool is maintained. On the last point: the most recent release listed is v1.6.0 on 2026-08-26, and the repository is not archived.

Licence, upgrade path and what maintenance costs you

CodeGraph is MIT licensed, per both the README badge and the license field in package.json. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a summary of the licence text, not legal advice; read LICENSE in the repository if the distinction matters to your organization.

The practical licence implication here is small, because the tool runs locally and does not send your code anywhere. The README states it is 100% local, and there is a separate TELEMETRY.md plus telemetry-worker/ and telemetry-dashboard/ directories in the repository, so telemetry exists as a subsystem and you should read TELEMETRY.md to learn what it collects and how to turn it off. That is the one place where "100% local" and a telemetry directory need reconciling on your own terms.

Upgrade cost is low by design. codegraph upgrade handles bundle, npm and npx installs in place, and codegraph upgrade --check reports availability without changing anything. The release cadence visible in the release list is roughly monthly: v1.4.1 on 2026-07-10, v1.5.0 on 2026-07-21, v1.6.0 on 2026-08-26. The last push to the repository was on 2026-08-26.

What you own after adopting: an MCP entry in each agent's config, a .codegraph/ directory per project, and a watcher process per project. codegraph uninstall and codegraph uninit exist for both halves of that, which is more reversal tooling than most tools of this kind ship.

Editorial conclusion

Adopt CodeGraph if your agent already burns a large share of its budget on grep, glob and Read calls before it starts editing, and if you are comfortable running a local indexer plus a watcher in every repository. Skip it for throwaway scripts, for repositories in languages outside the documented set, or if you need a hosted, shared index across a team, since the README describes CodeGraph as 100% local and the hosted product is still described as an early beta. Before rolling it out, run codegraph init in one mid-sized repository, then run codegraph uninstall --keep-cli once to see exactly which agent config files it rewrites, and check the .codegraph/ directory size that init leaves behind.

Frequently asked questions

Official sources

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