roam-code

Roam is a local codebase intelligence layer built for teams running AI coding agents like Claude Code, Cursor, Codex, and Gemini in real repositories. It indexes a codebase into a local SQLite graph, exposes 285 CLI commands and 244 MCP tools, and operates entirely on-machine with no API keys and no automatic source-code upload. The project is Apache 2.0 open source, built by a solo founder (Dimitris, handle: Cranot) operating from Athens, Greece.

What It Is

Roam sits between an AI coding agent and the codebase it edits. Before the agent's first token, Roam compiles structural facts — callers, blast radius, affected tests, clone siblings, layer violations, algorithmic risk — into a compact envelope the agent can consume directly. After the agent edits, Roam runs a verify loop that checks naming conventions, import resolution, secrets leakage, and structural risk, then gates the PR with a signed ChangeEvidence packet. The core engine is a SQLite-backed call graph built from tree-sitter ASTs across 28 language families, with six cross-language bridges (Salesforce Apex → Aura, REST front-end → back-end routes, Django ORM, .proto stubs, Jinja/Django templates, env var → config).

The Task Compiler

Roam ships a task compiler that classifies an incoming prompt into one of 23 intent procedures (deterministic, zero model calls), pre-executes the matching code-graph probes locally (~90 ms warm), and injects the answers into the prompt before the model sees it. The homepage reports a head-to-head benchmark on Claude (June 2026, 41 cells) showing median reductions of −83% agent turns, −80% input tokens, and −63% cost on navigation and comprehension tasks versus vanilla Claude. A routing replay on 723 real prompts found 57% of envelopes shipped pre-executed answers and a further ~33% shipped structured facts. For Claude Code, the compiler wires in with one command: roam hooks claude --write.

What Roam Catches

The tool is organized around three classes of structural consequence that agents and human reviewers tend to miss:

• Blast radius not measured — roam preflight <symbol> reports callers, affected tests, complexity, coupling, and fitness before any edit; git diff | roam critique exits with code 5 on high-severity findings.
• Clones not updated — when an agent fixes a bug by pattern-matching, Roam flags unchanged copies of the same pattern across the codebase with AST-exact + identifier-rename confidence scores.
• Runtime-hot paths treated as cold — roam critique --runtime weights blast radius by production traffic to surface the paths that matter most.

Roam also runs algorithmic risk review (roam math / roam algo): a 34-task anti-pattern catalog that catches code that passes tests but fails at scale — nested-loop O(n²) lookups, N+1 queries, regex compiled inside hot loops, repeated JSON parsing, quadratic string concatenation, and branching recursion without memoisation.

Architecture and Deployment Model

The analysis pipeline runs entirely locally: git file discovery → tree-sitter AST parsing → symbol/reference extraction → graph resolution → PageRank/betweenness/complexity metrics → Louvain community detection → SQLite storage in .roam/index.db. A 100k-LOC repo indexes in roughly 20–40 seconds on a laptop; incremental rebuilds after a PR's worth of changes are sub-second. The MCP server exposes 8 selectable presets (core, review, refactor, debug, architecture, compliance, compile-curated, full); the default core preset ships 17 tools to keep the agent prompt tight. Every MCP response is scrubbed for secrets on egress and gated against an active mode (read_only / safe_edit / migration / autonomous_pr) with HMAC-linked decision receipts.

Update: v14.0.0 (August 2026)

The latest release is v14.0.0, published 2026-08-08. The preceding v13.10 (2026-07-28) introduced privacy-preserving transcript mining for repeated-work interventions, a strict Verify receipt binding every edited Claude turn, and a generation-bound lifecycle marker for interrupted indexes that forces a full non-light rebuild before analysis. Earlier notable releases include v13.6 (secrets leak gate by default, symbol-keyed suppression, 16× faster verify --auto), v13.5 (Claude Code adapter via roam hooks claude --write), and v13.0 (Agent-OS control plane with HMAC-chained run ledger, multi-agent leases, and 4 cumulative modes). The GitHub repository shows 509 stars and 49 forks as of the data snapshot.

Who It Is For and When to Skip It

Roam is designed for teams where AI agents write real PRs in multi-service or multi-module codebases, and for teams that need review evidence they can hand to an auditor (SOC 2 CC8.1, ISO 42001, EU AI Act). The homepage explicitly recommends skipping Roam for tiny single-file repos with no AI-generated PRs and no structural review pain. It is not a replacement for semantic reviewers (CodeRabbit, Greptile, Qodo) or SAST tools (SonarQube, CodeQL) — it adds the structural layer those tools do not see: callers, clones, layers, tests, and hot paths.