Stronger AI Coding Agents Burn More Tokens: How roam-code's Code Graph Cuts Costs 63%

Project Overview

roam-code (Cranot/roam-code) is a local code-graph CLI and MCP server that parses a repository into a SQLite graph of functions, classes, calls, imports, and inheritance across 28 languages. The graph is built once with tree-sitter, then queried by AI coding agents via CLI or MCP (Model Context Protocol) to answer questions like "who calls handleSave", "what does this change affect", and "which tests are related". The project is Apache-2.0 licensed, written in Python, with 517 stars, 2,651 commits since February 2026 (v14.0.4 as of September 2026), and is largely a single-maintainer effort (2,310 of 2,321 commits by Cranot).

Why Existing Approaches Fall Short

grep / ripgrep : returns name matches, not relationships; cannot distinguish real calls from comments or strings.

LSP : excels at real-time type checking in editors, not whole-repo batch queries.

RAG context engines : chunk code, embed vectors, retrieve top-k similar chunks; chunks lack edges, so "looks similar" ≠ "actually related".

roam-code's architecture document contrasts RAG's path (agent → vector store → top-k chunks → hope for relevance) with its own (agent → graph query → ranked symbols → precise references). Edges are first-class citizens; symbol importance is ranked with PageRank.

Graph Construction: Parse Once, Query Everywhere

The pipeline runs in six steps: discover files (respecting .gitignore and .roamignore) → parse with tree-sitter → extract symbols → resolve edges → compute metrics (cognitive complexity, centrality, change frequency) → store in .roam/index.db (SQLite WAL mode). tree-sitter handles 28 languages including Python, TypeScript, Go, Rust, Java, Terraform, GitHub Actions YAML, and SQL DDL.

Performance claims: 200 files in 3–5 seconds, 3,000 files in ~2 minutes, incremental refresh on unchanged files under 1 second. The same index serves CLI, MCP, and CI gates. Text search uses SQLite FTS5 full-text index combined with graph-structure ranking; roam grep --whole-symbol aggregates scattered matches into complete function bodies.

Before Editing: Task Compiler Injects Precise Context

When an agent asks "where is login validated", a hook intercepts the query, runs a graph lookup, and packages a small envelope with line-numbered callers and relevant source snippets into the prompt — the model reads zero files itself. Official 41-pair experiments (June 2026, v13.7 kernel) on the same repo showed for navigation/understanding tasks: median agent turns dropped from 6 to 1, input tokens from 271K to 53K, single-task cost from $1.30 to $0.48 (83% fewer turns, 80% fewer tokens, 63% cost reduction). The compiler also routes economically: replaying 723 real prompts, 57% had answers directly in the graph (envelope injected, p50 compile latency 0.45s), while generative tasks like "write a test" skipped injection entirely to avoid pure overhead.

After Editing: Verification Gates That Cannot Be Bypassed

roam hooks claude --write

installs a post-edit hook: roam verify --auto runs naming conventions, import resolution, secret detection, complexity checks, and circular-dependency detection. The tool uses fail-open for pre-edit context (if graph lookup fails, don't block) but fail-closed for post-edit verification (missing evidence, malformed output, or failed checks all block completion). Completion shifts from "model says done" to "gate says passed".

Import checking resolves every import against the index, standard library, or declared dependencies; unresolved imports are flagged as "suspected hallucination" with did-you-mean suggestions. Secret scanning matches cloud keys, tokens, PEM blocks, and custom sensitive-word lists across all changed files. roam preflight reports blast radius before changes; example for open_db:

$ roam preflight open_db
VERDICT: Significant risk — 17922 symbols in blast radius
  Blast radius:   17922 symbols in 1732 files
  Affected tests: 681 direct, 14126 transitive
  Complexity:     cc=5, nest=2

Enterprise teams can use guard-pr to emit signed Agent Change Proof Bundles (SARIF) into GitHub Check Runs as PR gates.

Honest Experimental Reporting

The README discloses limitations alongside numbers: each of the 41 experiment groups had only 2–3 samples; bug-fix benchmark passed 10/10 but with n=10 the 95% CI is [72%, 100%] and token usage actually increased; A/B tests were run on v13.7 and not re-run on later versions. Failed experiments are kept: trivial questions initially cost 80% more (envelope overhead), code-generation tasks 17% more — later fixed by routing logic, but the failure record remains. The only pre-registered, holdout-validated result is repair-intent retrieval (given a bug-fix diff, find other files needing the same fix): on 576 real fixes across 12 third-party repos (fastapi, httpx, pytest, etc.), ranking quality beat lexical search, but authors call it "real and modest improvement, not a leap".

Getting Started: Four Commands

pip install "roam-code[mcp]"
cd /path/to/your/repo
roam init          # build index
roam health        # whole-repo health score (0-100)

Requires Python 3.10+; works with pipx or uv. Without [mcp] it's CLI-only. roam preflight <func> shows blast radius; roam health self-reports scores (e.g., 77/100 with 65 critical issues, flagging "god components"). Integration with Claude Code: roam hooks claude --write (uninstall with --uninstall). For other tools, roam describe --write injects usage into CLAUDE.md or .cursor/rules. MCP exposes 246 tools but only 17 core tools are enabled by default — avoiding token bloat from tool descriptions.

Positioning Against Alternatives

vs ripgrep : grep gives names, roam gives relationships; "who calls / impact" has no competitor; pure text search still faster with grep.

vs LSP : LSP for real-time editor checks; roam for whole-repo relations, Git history, architecture metrics — complementary.

vs SonarQube / CodeScene : quality platforms target human reports and gates; roam targets agent queries and gates; both can coexist in CI via SARIF.

vs CodeRabbit / Greptile : those read "semantics" for PR review; roam reads "graph" — who calls the changed function, what layer it sits in — different focus, potentially complementary.

vs RAG context engines : similarity retrieval vs deterministic graph query; for reproducible, explainable answers graph wins; for fuzzy semantic association embeddings have a place.

Costs and Risks, Stated Plainly

Documentation burden : 287 commands, 246 MCP tools; README requires patience. Core preset and five-verb starter mitigate but learning curve is real.

Engineering maturity : 7 months, single maintainer, 517 stars. Official container images paused for security review. Evaluations use n=1–3 samples. Calibrate thresholds on your own repo before using as CI gate.

Static analysis boundary : dynamic dispatch, reflection, eval calls cannot enter graph; secondary languages get only basic symbol extraction; 100k-file monorepo initial build acknowledged as slow.

Bus factor = 1 : heavy single-person project. Mitigation: engine is local SQLite + Apache-2.0; index format and code remain yours if development stops.

AI coding tools in 2026 are shifting competition from "who writes more code" to "who verifies reliably". roam-code bets on determinism: the graph is deterministic, queries are deterministic, gates are deterministic. It doesn't predict your codebase — it remembers it. Even if you don't adopt it, one idea is worth stealing: turn "done" from a model's self-report into a local gate that must pass. The more diligent the agent, the more valuable that gate becomes.

GitHub:

github.com/Cranot/roam-code