{"slug": "codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls", "title": "CodeGraph: Pre-Indexed Code Knowledge Graphs for Agent Tool Calls", "summary": "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.", "body_md": "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.\n\nThe 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.\n\nCoding agents typically operate in two modes:\n\nThis 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.\n\nCodeGraph 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.\n\nCodeGraph splits into two layers:\n\n**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.\n\n**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.\n\nThe 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).\n\nThe graph lives in a local SQLite database. Schema looks like this:\n\n`id`, `type` (function/class/variable), `name`, `file_path`, `line_start`, `line_end`, `signature`\n`source_id`, `target_id`, `relationship` (calls/imports/extends)\nSQLite 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.\n\nThe MCP server exposes two query modes:\n\n**Structured queries**: Direct graph operations. Example:\n\n```\n{\n  \"tool\": \"codegraph.find_callers\",\n  \"arguments\": {\n    \"function_name\": \"authenticate\",\n    \"max_depth\": 2\n  }\n}\n```\n\nReturns a list of functions that call `authenticate`, plus functions that call those functions (up to depth 2).\n\n**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.\n\nNatural language queries add 50-200ms latency but reduce the need for agents to understand the graph schema.\n\nFile watching uses platform-native APIs (FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows). When a file changes:\n\nExample: You rename a function from `login` to `authenticate`. The kernel:\n\nThis 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.\n\nCodeGraph handles polyglot repos by treating imports as opaque edges. If a TypeScript file imports a Python module, the graph stores:\n\n```\nNode: TypeScript function `fetchData`\nEdge: imports → Python module `data_loader`\n```\n\nThe 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.\n\nFor 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.\n\nCodeGraph ships with MCP server configs for Claude Code, Cursor, Codex, and others. The agent sees CodeGraph as a tool with these capabilities:\n\n`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.\nAgents call these tools instead of reading files. Example flow:\n\n`find_definition(\"authenticate\")` to locate the function.`find_callers(\"authenticate\")` to see where it's used.\nThis reduces token usage by 60-80% for typical refactoring tasks.\n\n| Scenario | CodeGraph Benefit | Limitation | \n|---|---|---|\n| Large monorepo (10K+ files) | High. Avoids scanning thousands of files. | Initial indexing takes 5-10 minutes. | \n| Frequent refactors | High. Agents query structure instead of reading. | Graph updates lag by 50-200ms after file save. | \n| Polyglot codebase | Medium. Cross-language imports work, but deep analysis requires multiple parsers. | Parser support varies. Obscure languages may not work. | \n| Small project (<100 files) | Low. File scanning is fast enough. | Overhead of running the kernel isn't worth it. | \n| Dynamic languages (Python, Ruby) | Medium. Static analysis misses runtime behavior. | Graph shows imports and calls, but not dynamic dispatch. | \n\n**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.\n\n**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.\n\n**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.\n\n**Observability**: The MCP server logs every query with timing data. You can pipe logs to Prometheus or Datadog to track:\n\nCodeGraph runs as a local daemon. Install via npm:\n\n```\nnpm install -g @colbymchenry/codegraph\ncodegraph init /path/to/repo\ncodegraph serve\n```\n\nThe kernel starts in the background and watches the repo. The MCP server listens on `localhost:3000`. Agents connect via HTTP or WebSocket.\n\nFor 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.\n\nCodeGraph 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:\n\nThe kernel has read-only access to the file system. It never writes to source files, only to the SQLite database.\n\n**Use CodeGraph when**:\n\n**Avoid CodeGraph when**:\n\nThe 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.", "url": "https://wpnews.pro/news/codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls", "canonical_source": "https://dev.to/mech_app_ai/codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls-1fg0", "published_at": "2026-11-20 00:10:48+00:00", "updated_at": "2026-11-20 00:13:03.090806+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "agent-protocols", "ai-tools", "large-language-models"], "entities": ["CodeGraph", "Claude Code", "Cursor", "Codex", "GitHub", "SQLite", "Neo4j", "tree-sitter"], "also_reported_by": [], "takeaway": "Pre-indexing a codebase into a persistent symbol-and-edge graph served over MCP lets agents answer caller and dependency queries directly, avoiding the 50+ file reads a 10,000-line monorepo session can otherwise require, with incremental updates landing in 10-50ms.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls", "markdown": "https://wpnews.pro/news/codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls.md", "text": "https://wpnews.pro/news/codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls.txt", "jsonld": "https://wpnews.pro/news/codegraph-pre-indexed-code-knowledge-graphs-for-agent-tool-calls.jsonld"}}