CodeGraph

Overview

CodeGraph is a pre-indexed code knowledge graph designed specifically for AI coding assistants like Claude Code, Codex, Cursor, and OpenCode. It enables AI agents to understand codebases more efficiently by providing structured knowledge about code relationships, dependencies, and architecture. With over 6,700 GitHub stars, it has become a popular tool for improving AI coding productivity by reducing token usage and tool calls while maintaining 100% local processing.

The core insight behind CodeGraph is that AI coding assistants often waste tokens and tool calls by repeatedly exploring the same code relationships. By pre-indexing the codebase into a structured knowledge graph, CodeGraph provides instant access to code structure, dependencies, and relationships — dramatically improving AI coding efficiency.

Features

• Pre-indexed knowledge graph: Instant access to code structure and relationships
• Token optimization: Reduces token usage by providing structured context instead of raw code
• 100% local processing: All indexing and querying happens on your machine
• Multi-language support: Works with TypeScript, Python, Go, Rust, and more
• IDE integration: Plugins for VS Code, Cursor, and other editors
• Smart context retrieval: Fetches only the most relevant code for each query

Installation

npm install -g codegraph

Or as a library:

npm install codegraph

Quick Start

import { CodeGraph } from 'codegraph';

// Initialize and index a codebase
const graph = await CodeGraph.index('./my-project');

// Query the graph
const dependencies = await graph.getDependencies('src/main.ts');
const references = await graph.getReferences('UserService');

// Get structured context for AI
const context = await graph.getContextForFile('src/api/handler.ts');

Core Concepts

Knowledge Graph Structure

CodeGraph builds a graph with the following node types:

• Files: Source code files with metadata
• Symbols: Functions, classes, interfaces, variables
• Dependencies: Import relationships between symbols
• References: Where symbols are used

Query Types

Query	Description
getDependencies(symbol)	Get all symbols a symbol depends on
getReferences(symbol)	Find all places a symbol is used
getImplementations(interface)	Find all implementations of an interface
getContextForFile(file)	Get relevant context for understanding a file
search(query)	Semantic search across the codebase

Advanced Features

Incremental Indexing

// Watch for changes and update the graph
graph.watch().on('change', (file) => {
  graph.update(file);
});

Custom Symbol Extractors

// Add custom symbol extraction for your framework
graph.addExtractor({
  name: 'custom-framework',
  extract: (file) => {
    // Custom extraction logic
    return symbols;
  }
});

Integration with AI Assistants

// Get optimized context for an AI coding session
const context = await graph.getOptimizedContext({
  query: 'How do I add a new API endpoint?',
  maxTokens: 4000,
  includeTests: true
});

Examples

Reducing Token Usage

// Before: AI reads entire file (500 tokens)
const fileContent = fs.readFileSync('src/service.ts', 'utf8');

// After: AI gets structured context (150 tokens)
const context = await graph.getContextForFile('src/service.ts');
// Returns: symbol definitions, dependencies, key functions

Understanding Code Relationships

// Find all places a function is called
const callers = await graph.getReferences('processPayment');

// Find all implementations of an interface
const implementations = await graph.getImplementations('PaymentProcessor');

// Trace dependency chain
const deps = await graph.getDependencyChain('CheckoutController');

Pros

• ✅ Significantly reduces token costs and tool calls
• ✅ 100% local — no data leaves your machine
• ✅ Fast indexing and query performance
• ✅ Works with existing AI coding tools
• ✅ Open-source with active community
• ✅ TypeScript-first with Python support

Cons

• ❌ Requires initial indexing time for large codebases
• ❌ TypeScript-focused with limited language support
• ❌ Newer project with evolving API
• ❌ May need customization for complex architectures
• ❌ Some features still in beta

When to Use

• Large codebases: When you have thousands of files and need efficient navigation
• AI coding assistants: When using Claude Code, Cursor, or similar tools
• Refactoring projects: When you need to understand code relationships
• Onboarding: When new developers need to understand the codebase
• Cost optimization: When you want to reduce AI API costs

Use Cases

Use Case	Why CodeGraph
Large Codebases	Navigate thousands of files efficiently
AI Coding Assistants	Reduce token usage and tool calls for Claude Code, Cursor
Refactoring Projects	Understand code relationships before making changes
Developer Onboarding	Help new devs understand codebase structure quickly

Comparison with Alternatives

Feature	CodeGraph	Sourcegraph	GitHub Code Search	IDE Native
Pre-Indexed	✅ Yes	✅ Yes	⚠️ Partial	❌ No
AI-Optimized	✅ Yes	⚠️ General	❌ No	⚠️ Limited
Local Processing	✅ Yes	❌ Cloud	❌ Cloud	✅ Yes
Token Optimization	✅ Yes	❌ No	❌ No	❌ No
Multi-Language	⚠️ TS-focused	✅ All	✅ All	✅ All
Learning Curve	Low	Medium	Low	Low
Best for	AI coding	Enterprise search	Quick lookups	Daily dev

Best Practices

1. Index early — Run initial indexing before starting AI coding sessions
2. Use incremental updates — Enable file watching for real-time graph updates
3. Query with specific symbols — Use symbol names for precise lookups
4. Combine with AI assistants — Use CodeGraph context to reduce AI token costs
5. Customize for your stack — Add custom extractors for framework-specific patterns

Troubleshooting

Issue	Solution
Indexing slow	Exclude node_modules and build directories
Symbols not found	Verify language support and file extensions
Query returns empty	Check symbol name matches exactly
Memory high	Reduce index depth or exclude large directories

Resources

• GitHub Repository
• Documentation
• VS Code Extension
• Cursor Integration Guide