CodeGraph: 94% Fewer Tool Calls for Claude Code — Pre-Indexed Code Knowledge Graph

The Problem: Claude Code Burns Tokens Exploring Your Codebase

If you've used Claude Code on anything larger than a toy project, you've seen it: the Explore agent spawns, runs grep, glob, and Read across dozens of files, burns through tool calls, and racks up tokens — just to understand how your code is structured.

On a codebase like VS Code (4,000+ TypeScript files), a single exploration question used 52 tool calls and took nearly two minutes. That's expensive, slow, and frustrating.

CodeGraph by Colby Chenry solves this by building a local knowledge graph of your codebase before Claude Code ever touches it. Instead of scanning files, agents query the graph and get answers in 1–3 calls.

How CodeGraph Works

CodeGraph uses tree-sitter to parse your codebase into an AST (Abstract Syntax Tree), then builds a knowledge graph containing:

• Symbol relationships — functions, classes, interfaces, and how they reference each other
• Call graphs — which functions call which, across files and modules
• Code structure — module boundaries, imports, exports, type hierarchies
• Cross-language support — TypeScript, Python, Rust, Java, Swift, C++, Go, and more

When Claude Code's Explore agent needs to understand a codebase, instead of spawning grep/glob scans, it calls codegraph_explore and gets structured answers from the pre-built graph. Zero file reads. Zero redundant scans.

Benchmark Results: Real Codebases, Real Savings

CodeGraph was tested across six production codebases using Claude Opus 4.6 (1M context) with Claude Code v2.1.91. Each test spawned a single Explore agent with the same question — with and without CodeGraph:

The Swift Compiler result is especially impressive — 25,874 files and 272,898 graph nodes, and CodeGraph still brought it down from 37 calls to 6.

Getting Started

Installation is a single command with an interactive setup:

npx @colbymchenry/codegraph

Or initialize in your project directory:

cd your-project
codegraph init -i

The interactive installer automatically configures Claude Code to use CodeGraph as a tool. No manual config editing required.

What Happens Under the Hood

1. Parse: tree-sitter parses every source file into an AST
2. Index: Symbols, types, and call relationships are extracted and stored in a local graph database
3. Register: The codegraph_explore tool is registered with Claude Code's tool system
4. Query: When Claude Code spawns an Explore agent, it calls codegraph_explore instead of grep/glob

When Should You Use CodeGraph?

CodeGraph shines when:

• Large codebases — projects with hundreds or thousands of files where grep-based exploration is slow
• Complex architectures — microservices, monorepos, or deeply nested module structures
• Frequent exploration — when you're using Claude Code for architecture reviews, onboarding, or cross-cutting refactors
• Cost-sensitive workflows — fewer tool calls means fewer tokens, which means lower API bills

For small projects (under 50 files), the overhead of building the graph probably isn't worth it — Claude Code's native exploration is fast enough.

Comparison with Alternatives

• Claude Code's native Explore — works fine for small repos, but scales linearly with codebase size. CodeGraph makes exploration O(1) after indexing.
• Manual CLAUDE.md files — helpful for context, but static. CodeGraph captures the full call graph dynamically.
• Other code indexing tools — tools like Sourcegraph index code for search, but CodeGraph is specifically designed for AI agent consumption with structured graph queries.

Limitations

• Indexing time: Large codebases take time to parse. The Swift Compiler (25K+ files) likely takes several minutes to index.
• Language support: Depends on tree-sitter grammar availability. Most popular languages are covered, but niche ones may not be.
• Staleness: The graph needs re-indexing after significant code changes. There's no watch mode yet.
• Claude Code only: Currently designed specifically for Claude Code's tool system. Not yet available for Cursor, Copilot, or other AI coding tools.

The Bigger Picture: AI Coding Tools Are Getting Smarter About Context

CodeGraph is part of a growing trend: instead of throwing more tokens at AI coding problems, developers are building infrastructure that gives AI agents structured access to code knowledge.

This mirrors what happened with databases — raw file scanning (full table scans) gave way to indexed queries. CodeGraph does the same for AI code exploration.

As AI coding agents become more capable, expect to see more tools like this: pre-computed knowledge structures that let agents reason about code without brute-force scanning.

Resources

• CodeGraph on GitHub — source code, benchmarks, and documentation
• npm package — install via npx or npm
• tree-sitter — the parsing library CodeGraph is built on

Found this useful? Check out our other developer tool guides and Claude Code best practices for large codebases.