The CodeGraph platform is coming — for every PR, know exactly what to test, what could break, which flows are affected, and whether business logic is compromised.
No Node.js required — one command grabs the right build for your OS:
# 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
Already have Node? Use npm instead (works on any version)
npm i -g @colbymchenry/codegraph
CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts codegraph on your PATH but doesn't change your current shell — open a new terminal before the next step so the command resolves.
Upgrade any time with codegraph upgrade — it detects how you installed (bundle, npm, or npx) and updates in place. Add --check to see if an update is available, or codegraph upgrade <version> to pin one.
2. Wire up your agent(s)
In a new terminal, run the installer to connect CodeGraph to the agents you use:
codegraph install
Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot (VS Code, Copilot CLI, JetBrains IDEs) — wiring the CodeGraph MCP server into each. This is the step that connects CodeGraph to your agent; installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does not index any code; building each project's graph is the separate codegraph init in step 3. (Shortcut: npx @colbymchenry/codegraph downloads and runs this in one go.)
3. Initialize each project
cd your-project
codegraph init
codegraph init creates the local .codegraph/ directory and builds the full graph in the same step — one command, done.
4. No more syncing!
Auto-sync is enabled by default. CodeGraph watches the project and updates the graph on every file change — while your agent edits code, or you add, modify, or delete files. The index is never stale, and there is nothing to re-run.
5. See what your agent sees
codegraph ui
Opens the graph in your browser at http://127.0.0.1:4747 — callers on the left, the symbol's
source in the middle, what it calls on the right. See
Read your graph in the browser.
Uninstall
Changed your mind? One command removes CodeGraph from every agent it configured and the CLI itself — every install it finds (standalone bundle, npm global package, launcher link), shown to you before anything is deleted:
codegraph uninstall
Pass --keep-cli to remove only the agent configurations and keep the CLI installed.
Reverses the installer — strips CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (.codegraph/) are left untouched; remove those per-project with codegraph uninit. Use --target to remove from specific agents, or --yes to run non-interactively.
Language Support
Every language below gets the same treatment — full structural extraction and cross-file resolution into one graph, no per-language setup:
Per-language details — extensions, frameworks, and what exactly gets extracted — in Supported Languages.
Why CodeGraph?
When an AI agent needs to understand code — to answer a question or make a change — it discovers structure the slow way: grep, glob, and Read, one file at a time, rebuilding call paths and dependencies by hand. That's a pile of tool calls and round-trips before it even starts the real work.
CodeGraph hands the agent the exact code it needs in one call. It's a pre-built knowledge graph of every symbol, call edge, and dependency in your codebase — so instead of crawling files, the agent asks one question and gets back the relevant source, the call paths between those symbols (including dynamic-dispatch hops grep can't follow), and the blast radius of a change. Surgical context, not a file-by-file search — which means fewer tool calls and faster answers on every codebase, large or small.
A note on cost: CodeGraph's win on every codebase is precision — the agent stops crawling files and answers from the graph. On current models that precision is also a large direct saving: the 2026-08 re-measurement, on a harness that blocks the CLI in both arms, put it at 44% lower cost and 62% fewer tokens on average across the seven benchmark repos, because a strong model without the graph burns its budget re-deriving structure. Cost tracks how much discovery a question demands more than raw repo size: 57–78% on questions the file-reading agent needed 28–43 tool calls to answer, near-even where it got there in 7.
A note on context: the numbers above measure throughput — tokens processed, tools called, dollars spent to reach one answer. They don't measure what is still sitting in your context window afterward, and on that axis CodeGraph costs more, not less. Across the same seven repos in multi-turn sessions, CodeGraph's responses leave about 80% more retrieval context resident at the end of a session than a file-reading agent's do — on VS Code, 67k tokens against 18k. The mechanism is the same one that makes it fast: CodeGraph returns one dense, verbatim payload that answers the question and then stays in the window, where a grep-and-read agent churns through many small results that get evicted. Fewer tokens processed and a larger persistent footprint are both real at once. If you run long sessions in a small window, budget for it. Measured per-repo: docs/benchmarks/residual-context-occupancy.md.
Benchmark Results
Tested across 7 real-world open-source codebases spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question with and without CodeGraph, at the median of 4 runs per arm. Re-measured 2026-08-05 on Claude Opus 4.8 against the current build, on a harness that blocks the codegraph CLI in both arms — contamination row: 0 of 28 without-arm runs.
The universal win — every repo, every size: 88% fewer tool calls · 53% faster · 62% fewer tokens · 44% cheaper · file reads cut to zero on all seven repos.
With the index available, the agent answers from one to four codegraph_explore calls and stops. Without it, the agent burns its budget on discovery — up to 43 tool calls and 19 file reads re-deriving what the graph already knew. Every repo was faster with CodeGraph in this measurement — by 35% on the narrowest question, by 3.6× on the widest.
Codebase
Language
Tool calls
Time
File reads
Tokens
Cost
VS Code
TypeScript · ~11k files
2 vs 28
2.2× faster (58s vs 2m 10s)
0 vs 12
77% fewer
71% cheaper
Excalidraw
TypeScript · ~640
2 vs 43
3.6× faster (45s vs 2m 42s)
0 vs 18
84% fewer
78% cheaper
Django
Python · ~3k
3 vs 14
35% faster (54s vs 1m 23s)
0 vs 8.5
41% fewer
13% cheaper¹
Tokio
Rust · ~790
3 vs 29
2.6× faster (1m 3s vs 2m 43s)
0 vs 19
65% fewer
64% cheaper
OkHttp
Java · ~645
1 vs 6
43% faster (33s vs 58s)
0 vs 2
54% fewer
21% cheaper
Gin
Go · ~110
1 vs 7
39% faster (28s vs 46s)
0 vs 4
52% fewer
~even¹
Alamofire
Swift · ~110
4 vs 33
2.6× faster (54s vs 2m 22s)
0 vs 16.5
59% fewer
57% cheaper
¹ Cost tracks how much discovery the question demanded, which is why it varies far more than the other columns: 57–78% on repos where the file-reading arm needed 28–43 tool calls, but only 13% on Django and even on Gin, where it got there in 14 and 7. The with-arm still answered in 3 and 1 calls with zero file reads. File reads = median files opened — the surgical-context win in one column: the agent never reads a file on any of the seven repos when CodeGraph is present.
Per-repo breakdown — WITH vs WITHOUT (median of 4)
Codebase
Metric
WITH cg
WITHOUT cg
VS Code
Time / Tools / Tokens / Cost
58s / 2 / 155k / $0.53
2m 10s / 28 / 670k / $1.80
Excalidraw
Time / Tools / Tokens / Cost
45s / 2 / 156k / $0.54
2m 42s / 43 / 991k / $2.43
Django
Time / Tools / Tokens / Cost
54s / 3 / 183k / $0.55
1m 23s / 14 / 309k / $0.63
Tokio
Time / Tools / Tokens / Cost
1m 3s / 3 / 201k / $0.66
2m 43s / 29 / 573k / $1.83
OkHttp
Time / Tools / Tokens / Cost
33s / 1 / 107k / $0.39
58s / 6 / 230k / $0.50
Gin
Time / Tools / Tokens / Cost
28s / 1 / 87k / $0.31
46s / 7 / 180k / $0.31
Alamofire
Time / Tools / Tokens / Cost
54s / 4 / 209k / $0.54
2m 22s / 33 / 505k / $1.27
Full benchmark details
Methodology. Each arm is claude -p (Claude Opus 4.8, claude-opus-4-8) run headlessly against the repo with --strict-mcp-config: WITH = CodeGraph's MCP server enabled, WITHOUT = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, 4 runs per arm, median reported. Cost = the run's total_cost_usd; Tokens = total tokens processed, summed per assistant turn (input incl. cache reads + cache creation + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at --depth 1 and indexed by the same CodeGraph build that served them. Re-measured 2026-08-05 on the current build.
The codegraph CLI is blocked in both arms. A sanitized PATH plus a PreToolUse hook denies any Bash invocation of the CLI, in the WITHOUT arm as well as the WITH arm. This matters: without that block the control arm is not a control. On an unblocked harness we measured the WITHOUT agent finding the CLI on PATH and reaching CodeGraph through Bash in 26 of 28 runs — which distorts the comparison in both directions, since a CLI call is not counted as a tool call and its output still enters the window. Earlier published figures were produced without this block. In the run reported above, all 28 WITHOUT runs attempted the CLI and all 28 were blocked — 0 contaminated.
What is this?CodeGraph pre-indexes your codebase into a knowledge graph of every symbol, call edge, and dependency, so AI coding agents get the exact code they need in one call instead of crawling files.
Is this a standalone app, or something that lives inside my coding agent?It's a CLI plus an MCP server: the codegraph command builds and serves the graph, and your agent pulls context from it through MCP tool calls.
What does wiring it into my agent involve?Three steps: install the CLI (one command, or npm), run the agent installer to connect the agents you use, then codegraph init in each project builds the full graph.
Do I need Node or anything else installed first?Not for the main install: the one-command installer grabs a standalone build with its own bundled runtime, nothing to compile. If you already have Node, npm works instead.
It promises fewer tokens — does that mean a lighter context window too?Oddly, no: tokens processed drop (62% fewer on average), but the dense answers leave about 80% more retrieval context resident at session end, so long sessions in a small window need budgeting.
Will it run on my Mac, or is it Linux-only?Standalone builds exist for macOS, Windows, and Linux — the installer picks the right one for your OS, and npm covers any machine that already has Node.
Does any of my code get uploaded somewhere?No — indexing and queries run entirely on your machine; 100% local is the README's own tagline.
Which coding agents can it plug into?The installer auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and GitHub Copilot (VS Code, Copilot CLI, JetBrains IDEs).
Do I have to rebuild the index whenever my agent edits code?No — auto-sync is on by default: CodeGraph watches the project and updates the graph on every file change, so the index is never stale and there is nothing to re-run.
Can I browse the graph myself, or is it only for the agent?You can open it in your browser: callers of a symbol on the left, the symbol's source in the middle, and what it calls on the right.
How much difference does it actually make in practice?In benchmarks across seven real-world repos (VS Code, Excalidraw, Django, Tokio and more), agents made 88% fewer tool calls and ran 53% faster with file reads cut to zero.
CodeGraph pre-indexes your codebase into a knowledge graph of every symbol, call edge, and dependency, so AI coding agents get the exact code they need in one call instead of crawling files.