Can CodeGraph Cut Claude Code’s Token Usage by 94% and Boost Exploration Speed by 77%?

Project Overview

CodeGraph is an open‑source (MIT) semantic code‑intelligence tool for Claude Code. It builds a local knowledge graph from source code using the Tree‑sitter parser, indexing symbols, call graphs and structure. The tool runs locally, stores data in SQLite, and does not require external services or API keys.

Quick Start

Run the interactive installer: npx @colbymchenry/codegraph The installer can install globally, configure the MCP server in ~/.claude.json, set automatic permissions and optionally initialize the current project. After installation, restart Claude Code.

Initialize a project:

cd your-project
codegraph init -i

This creates a .codegraph directory containing a SQLite database.

Why CodeGraph?

Claude Code’s exploration agent scans files with grep/glob/read, consuming tokens for each tool call. CodeGraph provides a pre‑indexed knowledge graph, allowing direct symbol queries and reducing token usage.

Benchmark on six real‑world repositories shows an average of 92 % fewer tool calls and 71 % faster exploration. Specific results:

VS Code · TypeScript: 3 calls / 17 s vs 52 calls / 1 m 37 s (94 % reduction, 82 % speed‑up)

Excalidraw · TypeScript: 3 calls / 29 s vs 47 calls / 1 m 45 s (94 % reduction, 72 % speed‑up)

Claude Code · Python + Rust: 3 calls / 39 s vs 40 calls / 1 m 8 s (93 % reduction, 43 % speed‑up)

Claude Code · Java: 1 call / 19 s vs 26 calls / 1 m 22 s (96 % reduction, 77 % speed‑up)

Alamofire · Swift: 3 calls / 22 s vs 32 calls / 1 m 39 s (91 % reduction, 78 % speed‑up)

Swift Compiler · Swift/C++: 6 calls / 35 s vs 37 calls / 2 m 8 s (84 % reduction, 73 % speed‑up)

Core Features

Smart context building : a single tool call returns entry points, related symbols and code snippets.

Full‑text search powered by SQLite FTS5.

Impact analysis : trace callers, callees and the full impact radius of a symbol.

Real‑time sync using native OS file‑watch events (FSEvents, inotify, ReadDirectoryChangesW) with debounce.

Multi‑language support : 19 + languages including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Swift, Kotlin, etc.

Framework‑aware routing : automatic detection of routes in Django, Flask, FastAPI, Express, Laravel, Rails, Spring, Gin and others.

100 % local execution : all data stored locally in SQLite, no external API keys required.

CLI Commands

Common commands:

codegraph                # start interactive installer
codegraph install
codegraph init [path]    # initialize project (optionally index)
codegraph uninit [path]
codegraph index [path]    # full indexing
codegraph sync [path]     # incremental sync
codegraph status [path]   # view index health
codegraph query <search>   # symbol search
codegraph files [path]    # view indexed file tree
codegraph context <task>  # build AI task context
codegraph affected [files...] # impact analysis
codegraph serve --mcp    # start MCP server for Claude Code

The codegraph affected command can be combined with git diff to find affected tests in CI pipelines.

Node.js Library Example

import CodeGraph from '@colbymchenry/codegraph';
const cg = await CodeGraph.init('/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();

Troubleshooting

“CodeGraph not initialized” : run codegraph init in the project directory and restart Claude Code.

Slow indexing : ensure large directories are excluded in config.json, use the --quiet flag.

Database lock / WASM fallback : install native build tools (e.g., xcode-select --install on macOS, sudo apt install build-essential on Linux) and rebuild better-sqlite3.

MCP server connection issues : verify MCP configuration in ~/.claude.json and that the server starts with codegraph serve --mcp.

Missing symbols : wait for automatic sync (~2 s) or run codegraph sync; check language support and exclude settings.

Future Roadmap

Planned language additions include SQL, Terraform, R and dbt based on GitHub issue feedback.