codegraph

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)

CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer putscodegraphon your PATH butdoesn't change your current shell— open a new terminal before the next step so the command resolves.

Upgrade any timewithcodegraph upgrade— it detects how you installed (bundle, npm, or npx) and updates in place. Add--checkto see if an update is available, orcodegraph upgrade <version>to pin one.

In anew terminal, run the installer to connect CodeGraph to the agents you use:

Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — 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 doesnotindex any code; building each project's graph is the separatecodegraph initin step 3. (Shortcut:npx @colbymchenry/codegraphdownloads and runs this in one go.)

codegraph initcreates the local.codegraph/directory and builds the full graph in the same step — one command, done.

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.

Changed your mind? One command removes CodeGraph from every agent it configuredandthe CLI itself — every install it finds (standalone bundle, npm global package, launcher link), shown to you before anything is deleted:

Pass--keep-clito 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 withcodegraph uninit. Use--targetto remove from specific agents, or--yesto run non-interactively.

Every language below gets the same treatment — full structural extraction and cross-file resolution into one graph, no per-language setup:

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 oneverycodebase 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-07 re-validation measured60% lower cost and 69% fewer tokens on averageacross the seven benchmark repos, because a strong modelwithoutthe graph burns millions of tokens re-deriving structure. The savings scale with repo size and tangle — dramatic on VS-Code-class trees, modest on a 100-file project — and compound across a team's daily agent usage.

Tested across7 real-world open-source codebasesspanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture questionwithandwithoutCodeGraph, at themedian of 4 runs per arm.Re-validated 2026-07-21 onClaude Opus 4.8against the current build — the Rust kernel plus this cycle's resolution overhaul.

The universal win — every repo, every size: 89% fewer tool calls · 60% cheaper · 69% fewer tokens · file reads cut to zero on all seven repos.

With the index available, the agent answers from a couple ofcodegraph_explorecalls and stops. Without it, the agent burns its budget on discovery — up to57 tool calls and 4.3M tokensre-deriving what the graph already knew. TheTimecolumn averages 20% faster but is the noisiest metric: on two small repos a strong model's raw grep loop finishes the wall-clock race sooner while still spending 5–10× the tokens and money — noted per-row below.

¹ The small-repo floor effect: Opus 4.8 greps small trees fast enough to win wall-clock while spending ~5–10× the tokens and ~4–7× the cost — the with-arm still answers from zero file reads. ² OkHttp's without-arm got lucky in 5 calls; the with-arm answered in 1 call for ~$0.03 more.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)

Methodology.Each arm isclaude -p(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'stotal_cost_usd; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at--depth 1and indexed by the same CodeGraph build that served them. Re-validated 2026-07-21 on the current build (native Rust kernel, adaptive parallel resolution, scoped sync).

Why CodeGraph wins:with the index available, the agent answers directly — usually onecodegraph_explorereturns the relevant source — and stops, with zero file reads on every benchmark repo. Without it, the agent spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when querieddirectly, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.

CodeGraph's parsing engine is anative Rust kernel: 20 languages — TypeScript, JavaScript, Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, R, Lua, Luau (Metal and CUDA ride the C++ path) — parse in compiled code with one boundary crossing per file. Every language shipped only after its graphs provedbyte-for-byte identicalto the reference engine on real repositories, from small libraries up to the Linux kernel; platforms without a prebuilt binary and files with syntax errors fall back per-file automatically, same graph either way.

And it scales itself to the machine it's on.Worker pools, parallel resolution, and analysis caches are sized from what the system actually has — real core counts (container/cgroup-aware, so a VPS that grants 2 cores gets sized for 2, not the host's 64), honestly-measured available RAM on macOS and Linux, and the measured cost ofyourproject's resolution work:

- On a workstation:the full parallel pipeline — native parse workers, a multi-worker resolver pool that engages the moment it pays for itself, memory-gated analysis caches. The Swift compiler repository (27k files of Swift and C++) fresh-indexes in about 100 seconds; a one-file edit re-syncs in ~4.
- On a 2-core / 6GB VPS:the same graph, from a pipeline tuned tofinish— the Linux kernel (70k files, 2M symbols, 6.4M relationships) indexes to completion in under 12 minutes where RAM-first designs run out of memory before reaching 1%.
- Every day after day one:saving a file updates the graph in well under a second — the watcher fires 300ms after a lone save and syncs exactly what changed (~0.3s of work on a 4,400-file project, ~0.4s on the 27,000-file Swift compiler repo), never re-scanning the tree. Measured against the fastest competing indexer's re-index-on-change: 2–7× faster on medium and larger repos across a 31-repo, 30-language benchmark — and the gap widens with repo size, because their cost grows with the repository and ours grows with the change.

How auto-syncing works — and why you don't need to runcodegraph syncmanually

CodeGraph detects web-framework routing files and emitsroutenodes linked byreferencesedges to their handler classes or functions. Querying callers of a view/controller now surfaces the URL pattern that binds it.

Mixed iOS / React Native / Expo bridging

Real iOS and React Native codebases live across multiple languages — a Swift caller invokes an Objective-C selector that's been auto-bridged, a JS file calls into a native module via the React Native bridge, a JSX component delegates to a native view manager. Static tree-sitter extraction stops at each language boundary. CodeGraph bridges them socodegraph_exploreconnects the flow end-to-end across the gap — call paths and blast radius cross the boundary instead of stopping at it.

Validated on real codebases(small + medium + large for each bridge):

Each bridge emits edges taggedprovenance:'heuristic'withmetadata.synthesizedBy:set to a stable channel name (e.g.swift-objc-bridge,rn-event-channel,fabric-native-impl,expo-module-extract), so the agent can tell at a glance how a hop got into the graph.

- Ask which agent(s) to configure — auto-detects installed ones from:Claude Code,Cursor,Codex CLI,opencode,Hermes Agent,Gemini CLI,Antigravity IDE,Kiro
- Prompt to installcodegraphon your PATH (so agents can launch the MCP server)
- Ask whether configs apply to all your projects or just this one
- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (CLAUDE.md/AGENTS.md/GEMINI.md) — that's how subagents and non-MCP agents learn thecodegraph explorecommand, since the MCP server's own guidance only reaches the main agent. Removed cleanly bycodegraph uninstall.
- Set up auto-allow permissions when Claude Code is one of the targets

The installerwires up your agents only — it does not index your code.After it finishes, build each project's graph yourself withcodegraph init(step 3). One globalcodegraph installcovers every project; you runcodegraph initonce per project.

codegraph install --yes # auto-detect agents, install global codegraph install --target=cursor,claude --yes # explicit target list codegraph install --target=auto --location=local # detected agents, project-local codegraph install --print-config codex # print snippet, no file writes

Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.

Builds the per-project knowledge graph index, which then auto-syncs on every file change. A single globalcodegraph installworks in every project you open — no need to re-run the installer per project.

That's it — your agent will use CodeGraph tools automatically when a.codegraph/directory exists.

To keep something else out, add it to.gitignore. To pull a default-excluded directory backin(say you really do want a vendored dependency indexed), add a negation —!vendor/. The defaults apply uniformly, so committing a dependency or build directory doesn't force it into the graph; the.gitignorenegation is the explicit opt-in.

.gitignorecan't drop a directory you'vecommitted, though. For a vendored theme or SDK that's checked into the repo (e.g. a Metronic theme understatic/), list it underexcludeincodegraph.json— gitignore-style patterns, matched against repo-root-relative paths, honored on index, sync, and watch: