# CodeGraph pre-builds your call graph so an agent stops grepping one file at a time

> CodeGraph is a local CLI that builds a knowledge graph of symbols, call edges and dependencies into a .codegraph/ directory, then keeps it current on every file change and serves it to coding agents over MCP. The setup is three separate steps, and the README's own cost numbers shrink toward zero on questions that were cheap to find anyway.

**colbymchenry/codegraph** — 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.

- Repository: https://github.com/colbymchenry/codegraph
- Website: https://colbymchenry.github.io/codegraph/
- Stars: 72,369 · Forks: 4,646
- Language: C
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/colbymchenry-codegraph

## codegraph init builds the graph, and a file watcher keeps it current

The mechanism is a pre-built index rather than a search wrapper. One command creates a local .codegraph/ directory and builds the full graph in the same step, and auto-sync is enabled by default, so CodeGraph watches the project and updates the graph on every file change, whether an agent is editing or you add, modify or delete files yourself. What lands in the graph is every symbol, every call edge and every dependency, resolved across files into one structure, and the README claims call paths include dynamic-dispatch hops that grep cannot follow. Two consequences follow from the design. The index is a per-project build artifact, so every repository your agents touch needs its own codegraph init, and a fresh clone starts with no graph. It is also a background process holding a watcher on your working tree for as long as the index exists. Language coverage is uniform by design: the README says every supported language gets full structural extraction and cross-file resolution into one graph with no per-language setup, and it defers the per-language details of extensions and frameworks to a separate Supported Languages section, so the table of what is actually parsed lives outside the quick start.

## Three steps that are easy to collapse into one

The README is emphatic that these do not do what people assume. Installing the CLI does not connect anything to your agents. The step that connects CodeGraph is separate:

```bash
codegraph install
```

That command detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot across VS Code, Copilot CLI and JetBrains IDEs, wiring the CodeGraph MCP server into each. It still indexes no code. Building a project's graph is the third step, and it has to be repeated per repository:

```bash
cd your-project
codegraph init
```

So a team that ran only the first command has a binary on the PATH and no integration, and a team that ran the second has an integration and no data. The README notes a shortcut, npx @colbymchenry/codegraph, which downloads and runs the wiring in one go.

## The installer leaves your current shell untouched, and there are three of them

No Node.js is required, and the project bundles its own runtime, so nothing compiles at install time. The documented cost of the standalone bundle is a shell restart:

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
```

The installer puts codegraph on your PATH but does not change your current shell, and the README tells you to open a new terminal before the next step so the command resolves. That instruction is aimed at a human at a prompt and it is the wrong shape for a setup script or a CI stage, where the same shell has to carry on. A second install path exists for anyone who already has Node, npm i -g @colbymchenry/codegraph, and the project says the bundle, the npm global package and npx all count as separate installs. codegraph upgrade detects which one you used and updates in place, with --check to report availability and a version argument to pin.

## The 44% figure is the project's own benchmark, and the README undercuts it

The cost argument rests on numbers the project published about itself, from a 2026-08 re-measurement on a harness that blocks the CLI in both arms: 44% lower cost and 62% fewer tokens on average across seven benchmark repos. The more useful figure is the caveat attached to it. The saving was 57 to 78% on questions where the file-reading agent needed 28 to 43 tool calls to answer, and near-even where that agent got there in 7 tool calls. Cost tracks how much discovery a question demands, not repository size. So the tool earns its keep on open-ended questions about unfamiliar structure, and the benefit approaches nothing on a lookup a competent grep would have found immediately. A team piloting this should measure on the questions that are actually expensive, because a repository of small, well-named files is the case where the graph adds the least.

## The integration is MCP, and the installer writes into your agent's config

What gets installed into each agent is a CodeGraph MCP server entry, and the README describes uninstall as reversing the installer, stripping CodeGraph's MCP server config, instructions and permissions from each configured agent. Read that as a file-modification warning rather than a formality: the tool edits configuration and adds permissions on the machine of every developer who runs codegraph install, and the same README says the removal command shows you what it will delete before deleting it, which is the behaviour you want and the reason to read the diff on the way in. The narrower limitation is the integration surface itself. Because the contract is MCP, an agent that cannot speak MCP gets nothing from any of this, and there is no other documented path for wiring CodeGraph into a tool. Removal is more granular than installation, which is worth knowing before you install on a shared machine: --target restricts the change to specific agents, --yes makes it non-interactive, and --keep-cli drops the agent configurations while leaving the CLI in place. Project indexes under .codegraph/ survive an uninstall by design and are cleared separately with codegraph uninit, so a half-removed install is a state the commands do allow.

## 100% local today, with a hosted platform in the same tree

The package description claims 100% local, and the CLI keeps the graph in a local directory, so nothing about indexing requires a service. The same README then announces that the CodeGraph platform is coming, offering early beta access at getcodegraph.com and pitching per-PR answers about what to test, what could break and which flows are affected. The repository layout shows that work is not elsewhere: alongside src/, ui/, docs/ and site/ there are telemetry-dashboard/ and telemetry-worker/ directories and a TELEMETRY.md file, and the project also sells official support separately. Nothing in the documentation states what those telemetry pieces collect today. For a team whose requirement is that code never leaves the machine, that gap is the thing to close now, because the local-only guarantee describes the current CLI and not the product the README is steering people toward.

## The published package is dist/, so the Rust kernel arrives compiled

npm gets @colbymchenry/codegraph, and the manifest is narrower than the repository. The files list is dist, scripts and README.md, so src/, codegraph-kernel/, docs/ and the test suite never ship. Entry points are dist/index.js for the library, dist/index.d.ts for types, and a bin mapping codegraph to ./dist/bin/codegraph.js, which the build step has to mark executable with a chmodSync of 0o755. The README calls the kernel Rust powered and the repository language breakdown agrees, and the kernel is a separate build, bash scripts/build-kernel.sh, not part of the TypeScript build. The npm build itself also copies src/db/schema.sql and the .wasm files from src/extraction/wasm into dist, which is the boundary where per-language parsing lives. The consequence for a user is that you depend on compiled output, so a bug in extraction cannot be read from what npm gave you, and a bug report needs the repository rather than the installed package. The manifest also declares a ui workspace and an evaluation target, test:eval running vitest against __tests__/evaluation/, so the quality claims are checked by a harness that lives in the repository and not in the package you install.

## Conclusion

CodeGraph earns its place on a repository where agents keep re-deriving structure, and the honest test is the README's own caveat: it pays off on questions that cost a file-reading agent 28 to 43 tool calls, and comes out near-even on the ones it could answer in 7. Check that before you roll it out. Teams that cannot let a tool rewrite their agent configuration should read what `codegraph install` touches first, and anyone with a local-only requirement should settle TELEMETRY.md before the hosted platform opens its beta.

## FAQ

### what is codegraph

CodeGraph is a local CLI and MCP server that pre-builds a knowledge graph of every symbol, call edge and dependency in a codebase, so a coding agent can ask for the relevant source and the call paths between symbols in one call instead of reading files one at a time.

### How does CodeGraph work?

codegraph init creates a local .codegraph/ directory and builds the full graph. Auto-sync is on by default and updates it on every file change, and the agents read it over the CodeGraph MCP server that codegraph install wires into them.

### How do I set up CodeGraph?

Install the CLI, either with the install.sh curl command or npm i -g @colbymchenry/codegraph, then run codegraph install to wire the MCP server into your agents, then run codegraph init inside each project. The README states that installing the CLI does not connect anything and that codegraph install does not index any code.

### Is CodeGraph compatible with Codex?

Yes. The README lists Codex CLI among the agents that codegraph install detects and auto-configures, alongside Claude Code, Cursor, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot.

### is codegraph safe

The package describes itself as 100% local and the index lives in a project directory. The documented behaviour of codegraph install is that it writes MCP server config, instructions and permissions into each configured agent, and codegraph uninstall shows what it will remove before removing it. The repository also ships a TELEMETRY.md.

## Sources

- [Official documentation](https://colbymchenry.github.io/codegraph/)
- [Official README](https://github.com/colbymchenry/codegraph#readme)
- [Project repository](https://github.com/colbymchenry/codegraph)
- [Release notes](https://github.com/colbymchenry/codegraph/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/colbymchenry-codegraph