# roam-code

> Local codebase intelligence CLI and MCP server that gives AI coding agents a structural code graph before they edit, gates risky diffs before merge, and emits tamper-evident audit evidence — zero API keys, zero network egress by default.

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.

## Features
- Local SQLite code graph with zero API keys and zero network egress by default
- 285 CLI commands and 244 MCP tools across 8 selectable presets
- Task compiler: classifies prompts into 23 intent procedures and pre-executes code-graph probes in ~90ms
- Blast-radius analysis with PageRank-weighted caller graphs before any edit
- Clone detection with AST-exact and identifier-rename confidence scoring
- Algorithmic risk review: 34-task anti-pattern catalog (O(n²), N+1, regex-in-loop, etc.)
- Tamper-evident ChangeEvidence packets with HMAC-chained run ledger and in-toto v1 attestations
- SARIF 2.1.0 export for GitHub Code Scanning and GitLab CI (37 commands)
- 28 language families via tree-sitter with 6 cross-language bridges
- MCP server with runtime secret-redaction and mode-gated policy enforcement
- roam hooks claude --write: one-command compile-before/verify-after loop for Claude Code
- Multi-agent coordination: conflict-aware partitioning and parallel-agent lease management
- Architecture governance: layer violation detection, cycle detection (Tarjan SCC), Louvain clustering
- Incremental indexing: sub-second rebuilds after PR-sized changes
- CI/CD integration with GitHub Actions template and quality-gate exit codes
- roam guard-pr: one-call CI gate emitting Agent Change Proof Bundle v1 with closed-enum verdict

## Integrations
Claude Code, Cursor, Windsurf, VS Code, OpenAI Codex CLI, Gemini CLI, Amp (Sourcegraph), GitHub Actions, GitLab CI, GitHub Code Scanning, PyPI, Sigstore / cosign, SonarQube (SARIF), CodeQL (SARIF)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source, Free tier available

## Version
v14.0.0

## Links
- Website: https://roam-code.com/
- Documentation: https://roam-code.com/docs/
- Repository: https://github.com/Cranot/roam-code
- EveryDev.ai: https://www.everydev.ai/tools/roam-code