Get Started

1. Install the CLI

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, 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. (Shortcut: npx @colbymchenry/codegraph downloads and runs this in one go.)}

3. Initialize each project

cd your-project
codegraph init -i

_{codegraph init just creates the local .codegraph/ index directory; adding -i (--index) also builds the initial graph in the same step. Without -i, run codegraph index afterwards to populate it.}

Uninstall

Changed your mind? One command removes CodeGraph from every agent it configured:

codegraph uninstall

_{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.}

Why CodeGraph?

When Claude Code explores a codebase, it spawns Explore agents that scan files with grep, glob, and Read — consuming tokens on every tool call.

CodeGraph gives those agents a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.

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. Each cell is the savings at the median of 4 runs per arm. Re-validated on Opus 4.8 (2026-06-02), on the current build (codegraph_explore as the primary tool).

Average: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls

CodeGraph cuts tokens, tool calls, and wall-clock time on every repo — across small, medium, and large codebases — and answers them with near-zero file reads, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. codegraph_explore shows the answer in full — the mechanism plus the exact methods you asked about, even when they're buried in a multi-thousand-line file — while collapsing redundant interchangeable implementations to signatures, so the response is sized to the answer rather than the file count. Cost stays flat-to-cheaper everywhere — largest on the small repos (Alamofire, OkHttp), roughly break-even on the most response-heavy ones (Excalidraw, Tokio), where CodeGraph trades the no-CodeGraph agent's many small grep/read round-trips for a few large, cache-heavy tool responses.

Key Features

agent writes src/Widget.ts
  → watcher fires (<100ms)
  → debounce (default 2s)
  → sync; Widget.ts is in the index
  → next agent query sees it

Framework-aware Routes

CodeGraph detects web-framework routing files and emits route nodes linked by references edges 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 so trace, callers, callees, and impact connect end-to-end across the gap.

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

Each bridge emits edges tagged provenance:'heuristic' with metadata.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.

Quick Start

1. Run the Installer

npx @colbymchenry/codegraph

The installer will:

• 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 install codegraph on 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 (the codegraph usage guide is delivered by the MCP server itself, so no instructions file is added to CLAUDE.md / AGENTS.md / etc.)
• Set up auto-allow permissions when Claude Code is one of the targets
• Initialize your current project (local installs only)

Non-interactive (scripting / CI):

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

2. Restart Your Agent

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

3. Initialize Projects

cd your-project
codegraph init -i

Builds the per-project knowledge graph index. A single global codegraph install works 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.

npm install -g @colbymchenry/codegraph

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__codegraph__codegraph_search",
      "mcp__codegraph__codegraph_explore",
      "mcp__codegraph__codegraph_callers",
      "mcp__codegraph__codegraph_callees",
      "mcp__codegraph__codegraph_impact",
      "mcp__codegraph__codegraph_node",
      "mcp__codegraph__codegraph_status",
      "mcp__codegraph__codegraph_files"
    ]
  }
}

How It Works

┌───────────────────────────────────────────────────────────────────┐
│                            Claude Code                            │
│                                                                   │
│   "How does a request reach the database?"                        │
│       calls CodeGraph tools directly — no Explore sub-agent       │
│                                 │                                 │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                       │
│                                                                   │
│       explore · search · callers · callees · impact · node        │
│                                 │                                 │
│                                 ▼                                 │
│                       SQLite knowledge graph                      │
│          symbols · edges · files · FTS5 full-text search          │
└───────────────────────────────────────────────────────────────────┘

1. Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).

2. Storage — Everything goes into a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search.

3. Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.

4. Auto-Sync — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed.

CLI Reference

codegraph                         # Run interactive installer
codegraph install                 # Run installer (explicit)
codegraph uninstall               # Remove CodeGraph from your agents (inverse of install)
codegraph init [path]             # Initialize in a project (--index to also index)
codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
codegraph sync [path]             # Incremental update
codegraph status [path]           # Show statistics
codegraph query <search>          # Search symbols (--kind, --limit, --json)
codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
codegraph affected [files...]     # Find test files affected by changes (see below)
codegraph serve --mcp             # Start MCP server
codegraph upgrade [version]       # Update to the latest release (--check, --force)

codegraph affected

Traces import dependencies transitively to find which test files are affected by changed source files.

codegraph affected src/utils.ts src/api.ts         # Pass files as arguments
git diff --name-only | codegraph affected --stdin   # Pipe from git diff
codegraph affected src/auth.ts --filter "e2e/*"     # Custom test file pattern

CI/hook example:

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

MCP Tools

When running as an MCP server, CodeGraph exposes these tools to Claude Code:

Library Usage

CodeGraph can be embedded directly. The npm package re-exports its programmatic API, so both import and require resolve the CodeGraph class in your own process — handy for embedding it in an app (e.g. an Electron main process).

import CodeGraph from '@colbymchenry/codegraph';
// CommonJS works too:
//   const { CodeGraph } = require('@colbymchenry/codegraph');

const cg = await CodeGraph.init('/path/to/project');
// Or: const cg = await CodeGraph.open('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();   // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();

Lower-level building blocks are exported from the same entry point for callers that drive the graph directly: DatabaseConnection, QueryBuilder, getDatabasePath, initGrammars / loadGrammarsForLanguages, and FileLock.

Embedding requirements

• Install from npm (npm i @colbymchenry/codegraph) so the matching per-platform package — which carries the compiled library and its dependencies — is fetched alongside the shim.
• The API runs on your runtime, so it needs Node 22.5+ for the built-in node:sqlite (Electron qualifies when its bundled Node is 22.5+). The CLI and MCP server are unaffected — they run on the self-contained bundled runtime.
• TypeScript types ship with the package. As with any Node-targeting library, keep @types/node available and skipLibCheck: true (the common default).

Configuration

There isn't any — CodeGraph is zero-config, with no config file to write or keep in sync. Language support is automatic from the file extension; there's nothing to wire up per language.

What it skips out of the box:

• Dependency, build, and cache directories — node_modules, vendor, dist, build, target, .venv, Pods, .next, and the like across every supported stack — so the graph is your code, not third-party noise. This holds even with no .gitignore.
• Anything in your .gitignore — honored in git repos via git, and in non-git projects by reading .gitignore directly (root and nested).
• Files larger than 1 MB — generated bundles, minified JS, vendored blobs.

To keep something else out, add it to .gitignore. To pull a default-excluded directory back in (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 .gitignore negation is the explicit opt-in.

Supported Platforms

Every release ships a self-contained build (bundled Node runtime — nothing to compile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):

See Get Started for the one-line install commands.

Supported Agents

The interactive installer auto-detects and configures each of these — wiring up the MCP server (which delivers its own usage guidance, so no instructions file is written):

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent
• Gemini CLI
• Antigravity IDE
• Kiro

Supported Languages

Measured cross-file coverage

Impact and blast-radius queries are only as good as the dependency graph behind them, so coverage is measured rather than asserted. Fair coverage = the share of symbol-bearing source files that have at least one resolved cross-file dependent — something that imports, calls, references, or (through a framework convention) routes to them — on a real-world benchmark repo per language. The residual is always a genuine static-analysis frontier (runtime dynamic dispatch, reflection / DI containers, framework-convention entry points, vendored third-party code), never hidden by gaming the denominator.

Framework routing is validated the same way, on a canonical app per framework: Express 100%, FastAPI 98%, Flask 100%, NestJS 96.8%, Gin 96.5%, Axum 100%, Rocket 93.8%, Vapor 100%, Laravel 92%, Rails 89.6%, React Router 100% — and the convention/reflection-heavy ones at their honest static-analysis ceiling: ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Django 74.1%.

Troubleshooting

"CodeGraph not initialized" — Run codegraph init in your project directory first.

Indexing is slow — Check that node_modules and other large directories are excluded. Use --quiet to reduce output overhead.

MCP hits database is locked — current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in node:sqlite in WAL mode, where concurrent reads never block on a writer. If you still see it:

• You're on an old (pre-0.9) install. Reinstall to get the bundled runtime — curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh (macOS/Linux), irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex (Windows), or npm i -g @colbymchenry/codegraph@latest.
• codegraph status shows Journal: other than wal — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 /mnt), so reads can block on writes. Move the project (with its .codegraph/ folder) onto a local disk.

MCP server not connecting — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that codegraph serve --mcp works from the command line.

Missing symbols — The MCP server auto-syncs on save (wait a couple seconds). Run codegraph sync manually if needed. Check that the file's language is supported and isn't inside a .gitignored or default-excluded directory (e.g. node_modules, dist).

Star History

License

MIT