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.

The Problem: Context Waste in Agent Tool Calls

Coding agents typically operate in two modes:

  1. Scan mode: Read entire files to understand structure, then discard context.
  2. Edit mode: Read files again to make changes.

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.

Architecture: Rust Kernel + MCP Server

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

Storage Format

The graph lives in a local SQLite database. Schema looks like this:

  • Nodes table: id, type (function/class/variable), name, file_path, line_start, line_end, signature
  • Edges table: 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.

Query Interface: Structured vs. Natural Language

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.

Incremental Updates: How the Kernel Avoids Full Re-Indexing

File watching uses platform-native APIs (FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows). When a file changes:

  1. Kernel reads the diff (not the full file).
  2. Parser identifies changed AST nodes.
  3. Kernel updates only the affected nodes and edges in the graph.

Example: You rename a function from login to authenticate. The kernel:

  • Updates the node name in the nodes table.
  • Finds all edges where source_id or target_id matches the old node.
  • Updates edge metadata to reflect the new name.

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.

Polyglot Codebases: Cross-Language Dependencies

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.

Agent Integration: MCP Server as a Tool Boundary

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:

  1. Agent receives task: "Refactor the authentication flow."
  2. Agent calls find_definition("authenticate") to locate the function.
  3. Agent calls find_callers("authenticate") to see where it's used.
  4. Agent reads only the files returned by the query (3 files instead of 20).
  5. Agent makes changes and commits.

This reduces token usage by 60-80% for typical refactoring tasks.

Trade-Offs: When CodeGraph Helps and When It Doesn't

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.

Failure Modes and Observability

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:

  • Query latency (p50, p99)
  • Cache hit rate (for repeated queries)
  • Kernel update lag (time between file save and graph update)

Deployment Shape

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.

Security Boundaries

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:

  • Run the MCP server behind a reverse proxy with API key auth.
  • Restrict file system access so the kernel can only read the target repo.
  • Disable natural language queries if you don't want to run a local LLM.

The kernel has read-only access to the file system. It never writes to source files, only to the SQLite database.

Technical Verdict

Use CodeGraph when:

  • You work on a monorepo with 1K+ files and agents repeatedly scan the same code.
  • Your agents spend more than 30% of their token budget on file reads.
  • You need cross-file analysis (call graphs, dependency trees) and don't want to build it yourself.

Avoid CodeGraph when:

  • Your codebase is under 100 files. File scanning is fast enough.
  • You use a language that tree-sitter doesn't support well (COBOL, Fortran, obscure DSLs).
  • You need runtime behavior analysis. CodeGraph only sees static structure.

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.

Source Links