Overview

Relevant source files

• .claude/skills/agent-eval/corpus.json
• CHANGELOG.md
• README.md
• __tests__/extraction.test.ts
• __tests__/installer.test.ts
• package-lock.json
• package.json
• src/bin/codegraph.ts
• src/extraction/grammars.ts
• src/extraction/languages/index.ts
• src/extraction/tree-sitter.ts
• src/installer/config-writer.ts
• src/installer/index.ts
• src/types.ts

CodeGraph is a local-first code intelligence system that builds a semantic knowledge graph from source code to accelerate AI-assisted development. It pre-indexes code structure, relationships, and semantics into a SQLite database, enabling AI assistants like Claude Code, Cursor, and others to query the graph instead of scanning files repeatedly.

By providing a structural map of the codebase, CodeGraph significantly reduces the overhead of LLM exploration. Benchmarks across real-world repositories show that CodeGraph results in 30% fewer tokens and 25% fewer tool calls compared to native agent exploration README.md11-12

---

Purpose

When AI assistants explore a codebase, they typically spawn Explore agents that scan files using grep, glob, and read_file tools. Each operation consumes tokens and requires multiple tool invocations. CodeGraph gives those agents a pre-indexed knowledge graph of symbol relationships, call graphs, and code structure README.md11-12

Key Benefits:

• Reduced Latency: Agents query the graph instantly instead of scanning files, resulting in faster answers README.md11-12
• Token Efficiency: Context is sized to the answer (e.g., specific methods) rather than full file contents. For large containers, CodeGraph returns structural outlines instead of a multi-thousand-character wall of source CHANGELOG.md16
• Precision: Resolves complex cross-file relationships, including static method calls, constants, and framework-specific conventions src/extraction/tree-sitter.ts34-37
• 100% Local: No external API dependencies or data exfiltration; the index lives in your project's .codegraph/ directory README.md11-12 README.md116-117
• Smart Deduping: codegraph_explore avoids re-sending source code already provided in the same conversation, using pointers to free space for new information CHANGELOG.md16

Sources: README.md1-128 CHANGELOG.md1-45 src/extraction/tree-sitter.ts1-37

---

Solution Architecture

CodeGraph orchestrates a multi-stage pipeline that transforms raw source code into a queryable graph. The system is designed to be embedded into AI agents via the Model Context Protocol (MCP).

System Component Diagram

Key Architectural Characteristics:

• Rust-Powered Kernel: A native Rust kernel accelerates extraction for performance-critical operations README.md16 src/extraction/tree-sitter.ts33
• Tree-sitter Powered: Uses web-tree-sitter and WASM grammars for high-fidelity AST parsing across 30+ supported languages package.json48-49 src/extraction/grammars.ts1-7
• Multi-Agent Support: Integrates with Claude Code, Cursor, GitHub Copilot (VS Code, CLI, JetBrains), Gemini, and more README.md30-38 src/installer/index.ts4-7
• Incremental Updates: Maintains index freshness through a background server and a file watcher that auto-syncs on file changes README.md125-128
• V8 Optimization: Persists V8 compile artifacts to skip recompiling unchanged sources, saving hundreds of milliseconds in worker-boot latency src/bin/codegraph.ts31-38

Sources: package.json1-61 README.md1-145 src/bin/codegraph.ts1-134 src/installer/index.ts1-85 src/extraction/tree-sitter.ts1-37 src/extraction/grammars.ts1-53

---

Core Capabilities

CodeGraph provides structural intelligence through the following entities and relationships:

Integration Tools (MCP)

The primary interface for AI agents is the MCP server, which exposes several specialized tools:

Tool	Purpose
codegraph_explore	Primary tool. Returns source code for relevant symbols, call flows, and "blast radius" impact. Features auto-deduplication CHANGELOG.md16
codegraph_search	Performs semantic and keyword search across the codebase using SQLite FTS5 CHANGELOG.md34
codegraph_callers	Identifies all functions/methods calling a specific node src/bin/codegraph.ts19
codegraph_impact	Analyzes the "blast radius" of changing a symbol src/bin/codegraph.ts21
codegraph_node	Retrieves detailed node metadata, including docstrings and signatures src/types.ts132-201
codegraph_status	Reports index freshness and pending changes src/bin/codegraph.ts15

Language Intelligence

CodeGraph extracts first-class symbols across a wide range of languages:

• Core Languages: TypeScript/JavaScript, Python, Go, Rust, Java, C#, C/C++, PHP, Ruby, Swift, Kotlin, and 20+ others CHANGELOG.md18 src/types.ts78-121
• Structural Nodes: Captures class, struct, interface, trait, function, method, enum, type_alias, and route src/types.ts22-46
• Framework Awareness: Specialized extractors for Svelte, Vue, Astro, Liquid, and Razor src/extraction/tree-sitter.ts23-32
• Deprioritization: A deprioritize setting in codegraph.json keeps helper scripts or generated output from crowding out product code in search results CHANGELOG.md24-25

Sources: src/types.ts22-123 CHANGELOG.md1-45 src/bin/codegraph.ts1-24 src/extraction/tree-sitter.ts23-32

---

Data Flow Pipeline

The following diagram bridges Natural Language queries to the underlying Code Entity Space:

Pipeline Phases

1. Extraction: The ExtractionResult is produced by parsing source files into nodes and edges. It handles language-specific nuances like C++ template stripping or Erlang MFA calls src/types.ts274-282 src/extraction/tree-sitter.ts78-85
2. Resolution: The system links UnresolvedReference entries to definitions. It includes framework-specific resolvers to handle implicit links like Svelte $state or Vue store collections src/types.ts281 src/extraction/tree-sitter.ts54-62
3. Indexing: Data is stored in a local SQLite database with FileRecord metadata to track content hashes and modified timestamps src/types.ts232-265
4. Querying: The CLI and MCP tools use NodeKind and EdgeKind filters to traverse the graph and build task-specific context src/types.ts22-72

Sources: src/types.ts22-282 src/extraction/tree-sitter.ts54-85 README.md124-128