CodeGraph Slashes Token Usage by 59% for Claude Code and Codex

When using Claude Code or Codex on medium‑to‑large codebases, each query can consume six‑figure token amounts because the model repeatedly scans many files.

CodeGraph architecture

CodeGraph builds a local knowledge graph of a repository:

Source files are parsed with tree‑sitter to produce an AST.

Language‑specific queries extract functions, classes, methods, imports, inheritance and call edges.

All nodes and edges are stored in a local SQLite database .codegraph/codegraph.db with an FTS5 full‑text index.

An MCP (Model Context Protocol) server exposes graph‑query capabilities to AI agents.

Traditional vs. graph‑based lookup

Traditional AI agents perform a Just‑in‑Time search: they grep for keywords, open each matching file, read the entire file, and iteratively build a call chain, often requiring dozens of steps.

With CodeGraph the agent queries the pre‑built graph and receives the complete call chain and symbol relationships in one or two steps, eliminating the repeated file‑scanning loop.

Benchmark results

Using Claude Opus 4.7 on seven real open‑source projects (four runs per question, median taken), the following improvements were observed:

Average cost reduction: 35 %

Token usage reduction: 59 %

Response time improvement: 49 %

Tool‑invocation count reduction: 70 %

Project‑specific gains included a VS Code‑scale project (≈73 % token reduction) and the Tokio Rust runtime (≈52 % cost reduction). The only variable between the WITH and WITHOUT groups was whether the CodeGraph MCP server was enabled.

Context engineering insight

The gains stem from moving the expensive “real‑time file scanning” step to a pre‑computed graph, providing the model with cleaner, more precise context. When context utilization exceeds roughly 40‑60 %, “Context Rot” occurs: excess noise degrades the model’s ability to surface key information.

Language and framework support

CodeGraph supports 19+ languages, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi.

For backend development it can automatically detect URL routes and their handler functions for 13 frameworks (Django, FastAPI, Express, NestJS, Laravel, Rails, Spring, etc.). Example: querying /api/users in a Django project returns the implementing view function without intermediate file lookups.

Incremental indexing

The MCP server watches file‑system change events, applies a 2‑second debounce to non‑code files, and incrementally updates the SQLite index, keeping the graph fresh during active development.

Comparison with other indexing tools

Cursor’s built‑in index relies on semantic similarity matching, whereas CodeGraph returns structured call‑graph relationships. The graph‑based retrieval aligns with GraphRAG concepts, shifting from text‑chunk relevance to entity‑relationship paths, which yields higher precision for code‑navigation queries.

Limitations

Reliance on tree‑sitter means that unconventional syntax or dynamically generated code may be omitted from the graph.

On macOS systems lacking Xcode command‑line tools, CodeGraph falls back to a compatibility mode that is 5–10× slower.

Installation and usage

Install with a single command: npx @colbymchenry/codegraph The installer detects installed AI coding tools (Claude Code, Cursor, Codex CLI, OpenCode, Hermes Agent) and automatically writes MCP configuration to ~/.claude.json (or .cursor/rules/ for Cursor). No manual configuration is required.

After installation, initialize the index: codegraph init -i When the index is built, AI agents automatically invoke the CodeGraph tool to answer code‑navigation questions.

Current release: v0.7.9, MIT‑licensed, requires Node.js 18+.

MCP protocol overview

MCP uses JSON‑RPC 2.0. An AI host connects to the CodeGraph MCP server, discovers the exposed tool capability, and calls it according to the protocol. Detailed protocol information is available in the referenced MCP documentation.

GitHub repository: https://github.com/colbymchenry/codegraph