CodeGraph: Pre-Indexed Code Knowledge Graphs for AI Coding Agents

If you use AI coding agents like Claude Code, Cursor, or Codex on large codebases, you have seen the pattern: the agent spawns explorer sub-agents that grep, glob, and read hundreds of files to understand the codebase structure. Each tool call costs tokens and time.

**CodeGraph** solves this differently. It pre-indexes your codebase into a knowledge graph — symbol relationships, call graphs, type hierarchies, and module structure — and exposes that graph to the agent via MCP (Model Context Protocol). The agent queries the graph instead of scanning files. The benchmark results speak for themselves: **25% cheaper, 57% fewer tokens, 23% faster, and 62% fewer tool calls** across 7 real-world codebases spanning 7 languages.

How CodeGraph works

CodeGraph operates in two phases:

1. **Indexing phase:** `codegraph index` analyses your project and builds a structured knowledge graph stored in `.codegraph/`. It parses imports, function definitions, class hierarchies, type references, and module dependencies to create a queryable symbol map.

2. **Query phase:** When your AI agent needs to understand the codebase, CodeGraph serves the relevant subgraph via MCP. The agent sees symbol definitions, callers, callees, and relationships instantly — no file scanning required.

The tool bundles its own Node.js runtime, so there is nothing to install except the single binary. It auto-configures your installed coding agents during setup.

Supported AI coding agents

CodeGraph works with all major coding agents:

• **Claude Code** (Anthropic)
• **Cursor**
• **Codex CLI** (OpenAI)
• **OpenCode**
• **Hermes Agent** (Nous Research)
• **Gemini CLI** (Google)
• **Antigravity IDE**
• **Kiro**

This cross-agent compatibility means you can invest in indexing your codebase once and get benefits across whichever agent you use.

Quick start installation

CodeGraph requires no Node.js installation — it ships with a bundled runtime:

```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

```

If you already have Node.js, you can use npm:

```bash

npx @colbymchenry/codegraph

or

npm i -g @colbymchenry/codegraph

```

The installer auto-discovers your installed coding agents and configures CodeGraph's MCP server for each one.

Initialise and index your project

```bash

cd your-project

codegraph init -i

```

The `-i` flag builds the initial knowledge graph immediately. On subsequent runs, use `codegraph index` to refresh the graph after code changes. The first index on a medium-sized project takes about 30–60 seconds.

Benchmark results across real-world codebases

CodeGraph was tested on 7 open-source projects comparing an agent answering architecture questions with and without the tool. Re-validated on Claude Opus 4.8 (29 May 2026):

| Codebase | Language | Cost | Tokens | Tool Calls |

|----------|----------|------|--------|------------|

| **VS Code** | TypeScript (~10K files) | 33% cheaper | 70% fewer | 80% fewer |

| **Django** | Python (~3K files) | 23% cheaper | 70% fewer | 77% fewer |

| **Tokio** | Rust (~790 files) | 35% cheaper | 70% fewer | 79% fewer |

| **Excalidraw** | TypeScript (~640 files) | 27% cheaper | 61% fewer | 70% fewer |

| **OkHttp** | Java (~645 files) | 11% cheaper | 48% fewer | 70% fewer |

| **Gin** | Go (~110 files) | 15% cheaper | 35% fewer | 47% fewer |

| **Alamofire** | Swift (~110 files) | 28% cheaper | 46% fewer | 13% fewer |

The savings are consistent across small, medium, and large codebases — and across languages. The biggest gains are on large codebases where agent file-scanning overhead is highest.

Practical workflow with AI agents

Once CodeGraph is configured, your coding agent automatically uses it:

```bash

In Claude Code or Codex or any supported agent

Just ask architecture questions naturally

codegraph> "Find all places that call the authentication middleware"

codegraph> "Show me the inheritance chain for PaymentGateway"

codegraph> "What files does the user registration module depend on?"

```

The agent queries the knowledge graph instead of spawning search agents, returning results in seconds instead of minutes.

If you are new to AI coding agents, see OpenMonoAgent.ai: Set Up a Local-First Coding Agent. For a comparison of the different agent options, read Claude Code vs Codex vs Kimi Code.

Re-indexing strategy

CodeGraph's index updates are incremental for most operations. After significant refactors:

```bash

codegraph index --full # Force full re-index

```

For CI/CD pipelines, add `codegraph index` post-deployment to keep the knowledge graph in sync with the main branch. Most teams find that a weekly full re-index with incremental daily updates is sufficient.

Uninstall

```bash

codegraph uninstall

```

This strips CodeGraph's MCP server config and instructions from every configured agent. Your project indexes remain in `.codegraph/` and can be removed with `codegraph uninit`.

Conclusion

CodeGraph is one of those tools that feels obvious once you see it. AI coding agents spend a huge fraction of their token budget on file discovery and codebase exploration. A pre-indexed knowledge graph eliminates that overhead entirely — and the benchmarks show it works across languages, project sizes, and agent types.

If you use AI coding agents on real codebases, CodeGraph will save you money and time on literally every query. It is 100% local, open source, and works with every major coding agent.

Source

• GitHub: colbymchenry/codegraph