CodeGraph Tutorial: Supercharge AI Coding Assistants with Semantic Code Intelligence

Created

Have you ever watched Claude Code burn through hundreds of thousands of tokens running grep, glob, and Read operations just to understand a codebase? CodeGraph solves this by giving your AI coding assistant a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure — so the agent queries the graph instantly instead of scanning files.

What is CodeGraph? CodeGraph is an open-source code knowledge graph tool (MIT license) that provides semantic code understanding to Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent via the MCP protocol. It uses tree-sitter to parse source code into a local SQLite index, supports 19+ programming languages, and delivers approximately 35% lower token costs, 70% fewer tool calls, and 49% faster responses in benchmarks.

Prerequisites

  • OS: macOS / Linux / Windows (all supported)
  • AI Coding Assistant: Claude Code, Cursor, Codex CLI, opencode, or Hermes Agent
  • Node.js: Optional — the install script bundles its own runtime

💡 Tip: If you already have Node.js installed, you can also use CodeGraph directly via npx or npm.

Overview

CodeGraph works in four stages:

  1. Extraction: tree-sitter parses source code into ASTs, extracting symbol nodes (functions, classes, methods) and relationship edges (calls, imports, inheritance)
  2. Storage: All data is stored in a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search indexing
  3. Resolution: After extraction, cross-references are resolved — function calls point to definitions, imports point to source files, class hierarchies are linked
  4. Auto-Sync: The MCP server monitors project changes using native OS file events, with a 2-second debounce before incremental sync — the graph stays fresh as you code

Step 1: Install CodeGraph

macOS / Linux:

1
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Windows (PowerShell):

1
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

The installer will automatically:

  • Detect your installed AI coding assistants (Claude Code, Cursor, etc.)
  • Install CodeGraph to your system PATH
  • Write MCP server configs and instruction files for each detected assistant
  • Initialize your current project

Install via npm

1
2
3
4
5
# Zero-install (temporary run)
npx @colbymchenry/codegraph

# Global install
npm i -g @colbymchenry/codegraph

💡 Tip: CodeGraph bundles its own Node.js runtime. You don’t need Node.js system-level installation when using the install script.

Non-Interactive Install (Scripting / CI)

1
2
3
4
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 only, no file writes

Step 2: Initialize Your Project

Navigate to your project directory and build the code knowledge graph index:

1
2
cd your-project
codegraph init -i

The -i flag triggers index building. After initialization, a .codegraph/ directory is created at the project root containing the SQLite database.

Step 3: Restart Your AI Assistant

After installation, restart your AI coding assistant (Claude Code / Cursor / Codex CLI / etc.) to load the MCP server.

Once restarted, when your assistant explores code in the project, it will automatically use CodeGraph’s MCP tools to query symbol relationships and code structure instead of blindly scanning files.

Step 4: Master the Core MCP Tools

CodeGraph exposes the following tools to AI assistants via the MCP protocol:

Tool Purpose Use Case
codegraph_search Find symbols by name Locate where a function/class is defined
codegraph_context Build relevant code context for a task Help AI understand a feature’s full implementation
codegraph_callers Find what calls a function Analyze modification impact scope
codegraph_callees Find what a function calls Understand a function’s dependency chain
codegraph_impact Analyze impact of changing a symbol Evaluate impact before refactoring
codegraph_node Get details about a specific symbol View function signature, source code
codegraph_files Get indexed file structure Quickly browse project structure
codegraph_status Check index health and statistics Debug indexing issues

Real-World Usage Example

When you ask Claude Code “How does user authentication work?”, the assistant will:

  1. Call codegraph_context to query symbols and code snippets related to authentication
  2. Get entry points, related symbols, and code directly — no file scanning needed
  3. Deliver a precise answer

Benchmark Results (from official benchmarks on 7 real-world codebases):

Metric With CodeGraph Without CodeGraph Improvement
Cost $0.42 $0.64 35% cheaper
Tokens 393k 1.4M 59% fewer
Response Time 1m 0s 1m 43s 49% faster
Tool Calls 7 23 70% fewer

💡 Tip: CodeGraph only helps when the AI assistant queries MCP tools directly. If the assistant delegates to Explore sub-agents that scan files, CodeGraph’s benefits won’t materialize. After installation, the assistant follows the optimal usage pattern automatically.

Step 5: Use the CLI Tools

Beyond running as an MCP server, CodeGraph provides a rich set of CLI commands:

1
2
3
4
5
6
7
codegraph status              # Show index statistics
codegraph search <keyword>    # Search symbols (--kind, --limit, --json)
codegraph files               # Show file structure (--format, --filter)
codegraph context <task>      # Build context for AI
codegraph sync                # Incremental sync (after file changes)
codegraph index               # Full re-index (--force)
codegraph affected src/foo.ts # Find test files affected by changes

codegraph affected — Smart Test Selection

When you’ve modified files, codegraph affected traces import dependencies to find which test files are impacted:

1
2
3
4
5
6
7
8
# Pass files directly
codegraph affected src/utils.ts src/api.ts

# Pipe from git diff
git diff --name-only | codegraph affected --stdin

# Custom test file filter
codegraph affected src/auth.ts --filter "e2e/*"

Supported Languages and Frameworks

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

Additionally, CodeGraph recognizes route files from 14 web frameworks, linking URL patterns to their handler functions: Django, Flask, FastAPI, Express, NestJS, Laravel, Drupal, Rails, Spring, Gin/chi/Actix, ASP.NET, Vapor, React Router, and SvelteKit.

Uninstall

Want to remove CodeGraph? One command:

1
codegraph uninstall

This strips CodeGraph’s MCP server config and instruction files from all configured AI assistants. Project indexes (.codegraph/) are left untouched — remove them with codegraph uninit.

FAQ

Q: Does CodeGraph require internet access?
A: No. CodeGraph runs entirely locally — all data is stored in a local SQLite database with no external APIs or services required.

Q: My AI assistant isn’t using CodeGraph after installation?
A: Verify these steps: ① You ran codegraph init -i to initialize the project; ② You restarted your AI assistant; ③ A .codegraph/ directory exists in your project root.

Q: Indexing is slow.
A: Make sure node_modules and other large directories are excluded via .gitignore. Files larger than 1 MB are automatically skipped.

Q: MCP connection reports “database is locked”?
A: Upgrade to the latest version (npm i -g @colbymchenry/codegraph@latest). Newer builds use WAL mode to avoid lock conflicts. If the issue persists, check if the project is on a network share or WSL2 /mnt path.

Q: Which AI assistants are supported?
A: Currently Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent. The installer auto-detects installed assistants.

Conclusion

You’ve learned the core capabilities of CodeGraph:

  1. ✅ Installed CodeGraph (one-command script or npm)
  2. ✅ Initialized project indexing
  3. ✅ Mastered core MCP tools (search, context, callers, callees, impact)
  4. ✅ Used CLI tools for symbol search and impact analysis
  5. ✅ Leveraged codegraph affected for smart test selection

CodeGraph’s core value is enabling AI assistants to query code semantically instead of blindly scanning files. In large codebases, this means lower token costs, faster responses, and fewer tool calls.

📖 Official repo: github.com/colbymchenry/codegraph
📦 npm package: @colbymchenry/codegraph

How to cite this article: Based on the official CodeGraph README (verified 2026-05-22) and GitHub API data. Benchmark data from official README: average 35% lower cost, 59% fewer tokens, 49% faster, 70% fewer tool calls.