cd /news/ai-agents/codegraph-pre-indexed-code-knowledge… · home › topics › ai-agents › article
[ARTICLE · art-172911] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

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.

key 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.

by read5 min views4 publishedNov 20, 2026

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_`

The kernel doesn't parse Python's internal structure from TypeScript. It just records the dependency. When an agent queries "what depends on data_?", it sees fetchData in the results.

For deeper cross-language analysis, you run the kernel with multiple parsers enabled. The Python parser indexes data_, 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.

── more in #ai-agents 4 stories · sorted by recency
── more on @codegraph 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/codegraph-pre-indexe…] indexed:0 read:5min 2026-11-20 · —