CodeGraph is a tool designed to enhance code exploration and understanding for AI-powered agents such as Claude Code, Cursor, Codex CLI, and OpenCode. Its primary function is to build a pre-indexed, semantic knowledge graph of a codebase, enabling agents to query code relationships, call graphs, and structural information instantly, rather than relying on traditional file scanning methods like grep or glob. This approach significantly reduces the number of tool calls and tokens consumed during code exploration, resulting in faster and more efficient workflows. Benchmark tests across various real-world codebases demonstrate that CodeGraph can reduce tool calls by up to 94% and speed up exploration by 77%, all while operating entirely locally without external dependencies or API keys.
The core of CodeGraph is its extraction and indexing process. It uses tree-sitter to parse source code into abstract syntax trees (ASTs), from which it extracts nodes (such as functions, classes, and methods) and edges (including calls, imports, inheritance, and framework-specific routes). This information is stored in a local SQLite database with FTS5 full-text search capabilities, allowing for rapid symbol lookup and context building. The system supports over 19 programming languages, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, and Pascal/Delphi. Additionally, CodeGraph is framework-aware, recognizing routing patterns in popular web frameworks like Django, Flask, FastAPI, Express, Laravel, Rails, Spring, Gin, Axum, ASP.NET, Vapor, React Router, and SvelteKit, and linking URL patterns to their handler functions or classes.
CodeGraph operates as an MCP (Multi-Command Protocol) server, exposing a suite of tools to agents. These tools include codegraph_search (symbol lookup), codegraph_context (context building for tasks), codegraph_callers and codegraph_callees (call flow tracing), codegraph_impact (impact analysis before code changes), codegraph_node (symbol details), codegraph_files (indexed file structure), and codegraph_status (index health and statistics). The knowledge graph is kept up-to-date through a native file watcher that uses OS-level events (FSEvents, inotify, ReadDirectoryChangesW) to detect changes and incrementally sync the graph, ensuring that the indexed information remains current as developers modify their code.
Installation and setup are streamlined via an interactive CLI installer, which auto-detects supported agents, configures them, and initializes projects. The installer can be run globally or locally, and supports scripting and CI workflows. Once initialized, agents automatically leverage CodeGraph tools when a .codegraph directory is present in the project. The configuration file (.codegraph/config.json) allows customization of indexed languages, exclusion patterns, framework detection, file size limits, and extraction options.
CodeGraph is designed for privacy and performance, operating entirely on the user's machine with no data leaving the local environment. Its integration with AI agents enables smarter, faster, and more context-rich code exploration, making it a valuable tool for developers seeking to improve their productivity and code comprehension, especially in large or complex codebases.
