Cranot/roam-code

pip install "roam-code[mcp]" (with MCP server for Claude Code / Cursor / Continue)
pipx install roam-code or uv tool install roam-code
From source: pip install git+https://github.com/Cranot/roam-code.git
Docker: docker build -t roam-code . && docker run --rm -v "$PWD:/workspace" roam-code index

Usage

• •roam init (index the repo into .roam/index.db, ~30s), roam health (0-100 score), roam preflight <symbol> (blast radius + tests + complexity before editing)
• •roam hooks claude --write — wires compile-before + verify-after hooks into Claude Code in one command (--uninstall to undo)
• •roam mcp — start the MCP server (default core preset, 17 tools; ROAM_MCP_PRESET=full for all 244)
• •roam verify --auto / --diff-only / --new-only — post-edit verification: imports firewall, secrets leak gate, naming, complexity
• •roam guard-pr --ci — one-call PR gate emitting an Agent Change Proof Bundle v1 with pass/needs_review/blocked verdict

Key features

• ✓Task compiler: recognizes the question type, runs code-graph lookups locally (~90 ms, zero model calls), and injects the answers into the prompt — measured −83% turns / −80% input tokens / −63% cost on navigation/comprehension tasks
• ✓Pre-change safety: roam preflight reports blast radius, affected tests, complexity, coupling, and fitness before an edit
• ✓Post-edit verification: import-resolution hallucination firewall, secrets leak gate, naming/duplicates/cycles checks, and a fix loop keyed by symbol
• ✓244 MCP tools in 8 selectable presets; 28 languages supported (Tier 1 parsers for Python, JS/TS, Java, Go, Rust, C/C++, C#, PHP, Ruby, Kotlin, Scala, Swift, Dart, SQL, YAML, Terraform, Vue/Svelte, Salesforce)
• ✓Tamper-evident ChangeEvidence packets (HMAC-chained run ledger + signed Code Graph Attestation), MCP runtime security (secret redaction, policy_decision modes), CI/CD via Guard and SARIF output

Best for

Giving AI coding agents local code-graph intelligence — blast radius, dependency answers, and safe-change gating — to cut token usage and token cost on large codebases.

Caveats

• ⚠Static analysis primarily — cannot trace dynamic dispatch, reflection, or eval'd code; import resolution is heuristic
• ⚠Not a real-time type checker (use an LSP); not a text search tool (ripgrep is faster)
• ⚠Free CLI is Apache 2.0 and never expires; paid layers: Roam Review from $99/mo, Roam Cloud $19/repo/mo, PR Replay $2,500 (Team) / $6,000 (Deep)
• ⚠Tier 2 languages get only basic symbol extraction via the generic tree-sitter walker
• ⚠Large monorepos (100k+ files) may have slow initial indexing; Windows process startup can add ~1.5s to every command