CodeGraph: Pre-Indexed Code Knowledge Graphs for Agent Tool Calls The CodeGraph project has built a pre-indexed code knowledge graph that lets coding agents query codebase structure through an MCP server instead of repeatedly reading files. A Rust-powered kernel uses tree-sitter to parse 40+ languages into a SQLite graph of symbols and relationships, updating incrementally on file changes in 10-50ms, while the MCP server exposes structured queries like find_callers and get_dependencies plus natural-language queries via a small embedded LLM. The project reports 78K+ GitHub stars and ships configs for Claude Code, Cursor, and Codex. Coding agents burn tokens on repeated file reads. Claude Code, Cursor, and Codex scan the same functions over and over because they lack persistent memory of codebase structure. CodeGraph solves this by maintaining a live semantic graph that agents query instead of scanning files. The project sits at 78K+ GitHub stars and trending 11 in TypeScript. It runs 100% local with a Rust-powered kernel that watches file changes and incrementally updates the graph. The MCP server exposes this graph as a tool boundary for agents. Coding agents typically operate in two modes: This pattern wastes tokens and introduces latency. A 10,000-line monorepo might require 50+ file reads per agent session. Each read costs tokens and round-trip time. CodeGraph pre-indexes the codebase into a queryable graph. Agents ask "show me all functions that call authenticate " instead of reading 20 files to find them. The graph persists across sessions, so repeated queries cost nothing. CodeGraph splits into two layers: Rust kernel : Watches file system events, parses code into AST nodes, and updates the graph incrementally. When you edit a function, only that function's subgraph updates. Full re-indexing happens only on initial setup or major refactors. MCP server : Exposes the graph as a tool boundary. Agents call structured queries like find callers function name or get dependencies module path . The server translates these into graph traversals and returns results as JSON. The kernel uses tree-sitter for parsing, which supports 40+ languages. Each language gets its own parser, but the graph schema is uniform: nodes represent symbols functions, classes, variables , edges represent relationships calls, imports, inheritance . The graph lives in a local SQLite database. Schema looks like this: id , type function/class/variable , name , file path , line start , line end , signature source id , target id , relationship calls/imports/extends SQLite handles query speed well for graphs under 100K nodes. For larger monorepos, the kernel can export to a graph database like Neo4j, but most projects stay under the SQLite threshold. The MCP server exposes two query modes: Structured queries : Direct graph operations. Example: { "tool": "codegraph.find callers", "arguments": { "function name": "authenticate", "max depth": 2 } } Returns a list of functions that call authenticate , plus functions that call those functions up to depth 2 . Natural language queries : The server embeds a small LLM Phi-3 or similar that translates plain English into structured queries. Example: "What functions depend on the database connection?" becomes a graph traversal for all nodes with edges to the db connection module. Natural language queries add 50-200ms latency but reduce the need for agents to understand the graph schema. File watching uses platform-native APIs FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows . When a file changes: Example: You rename a function from login to authenticate . The kernel: This takes 10-50ms for typical changes. Full re-indexing parsing every file happens only when you add a new language or change the graph schema. CodeGraph handles polyglot repos by treating imports as opaque edges. If a TypeScript file imports a Python module, the graph stores: Node: TypeScript function fetchData Edge: imports → Python module data loader The kernel doesn't parse Python's internal structure from TypeScript. It just records the dependency. When an agent queries "what depends on data loader ?", it sees fetchData in the results. For deeper cross-language analysis, you run the kernel with multiple parsers enabled. The Python parser indexes data loader , the TypeScript parser indexes fetchData , and the graph links them via the import edge. CodeGraph ships with MCP server configs for Claude Code, Cursor, Codex, and others. The agent sees CodeGraph as a tool with these capabilities: find definition symbol name : Returns file path, line number, and signature. find callers function name : Returns all functions that call the target. find dependencies module path : Returns all modules imported by the target. search symbols query : Full-text search across function and class names. Agents call these tools instead of reading files. Example flow: find definition "authenticate" to locate the function. find callers "authenticate" to see where it's used. This reduces token usage by 60-80% for typical refactoring tasks. | Scenario | CodeGraph Benefit | Limitation | |---|---|---| | Large monorepo 10K+ files | High. Avoids scanning thousands of files. | Initial indexing takes 5-10 minutes. | | Frequent refactors | High. Agents query structure instead of reading. | Graph updates lag by 50-200ms after file save. | | Polyglot codebase | Medium. Cross-language imports work, but deep analysis requires multiple parsers. | Parser support varies. Obscure languages may not work. | | Small project <100 files | Low. File scanning is fast enough. | Overhead of running the kernel isn't worth it. | | Dynamic languages Python, Ruby | Medium. Static analysis misses runtime behavior. | Graph shows imports and calls, but not dynamic dispatch. | Graph corruption : If the kernel crashes mid-update, the SQLite database can end up in an inconsistent state. CodeGraph includes a codegraph repair command that re-indexes from scratch. Parser errors : If a file has syntax errors, the parser skips it and logs a warning. The graph remains incomplete until you fix the syntax. Agents see a partial view of the codebase. Memory usage : The kernel holds the graph in memory for fast queries. A 100K-node graph uses ~500MB RAM. For larger repos, you can configure the kernel to use disk-backed storage, but queries slow down by 2-3x. Observability : The MCP server logs every query with timing data. You can pipe logs to Prometheus or Datadog to track: CodeGraph runs as a local daemon. Install via npm: npm install -g @colbymchenry/codegraph codegraph init /path/to/repo codegraph serve The kernel starts in the background and watches the repo. The MCP server listens on localhost:3000 . Agents connect via HTTP or WebSocket. For team deployments, you can run CodeGraph on a shared server and point multiple agents at the same MCP endpoint. This works if everyone on the team uses the same codebase. If developers work on different branches, each needs their own CodeGraph instance. CodeGraph runs locally and never sends code to external servers. The MCP server has no authentication by default, so any process on the same machine can query the graph. For production deployments, you should: The kernel has read-only access to the file system. It never writes to source files, only to the SQLite database. Use CodeGraph when : Avoid CodeGraph when : The project is stable but young. Expect rough edges in polyglot repos and large-scale deployments. The Rust kernel is solid, but the MCP server API may change as agent tooling evolves.