Cranot/roam-code

📚 What roam‑code is

roam‑code is a Python‑based, locally‑run static‑analysis toolkit designed for coding agents (LLM‑powered code‑generation tools). It builds a searchable map of a repository’s symbols—functions, classes, imports, and the connections between them—so an agent can ask questions like “who calls this function?” or “what tests are affected by this change?” without having to read every file.

The tool does no remote model calls; all heavy lifting happens on your machine. It ships as a CLI (roam) and an optional MCP (Model‑Control‑Protocol) server that lets agents talk to it via a standard tool‑calling interface.

---

🔧 Core features (as described in the README)

Feature	What it does	How you use it
Indexing / roam init	Parses the whole repo, builds a symbol graph covering 28 languages, 287 commands, and 246 MCP tools.	Run roam init (or roam index for a lighter build) in the repo root.
Pre‑flight checks (roam preflight <symbol>)	Estimates the blast radius of a change (how many symbols/files could be impacted) and reports related tests, complexity, coupling, etc.	roam preflight open_db – returns a risk verdict with concrete numbers.
Health summary (roam health)	Gives a quick overview of code structure, findings, and overall “health score”.	roam health after indexing.
Search (roam search <name>)	Finds symbols by name across the indexed graph.	roam search handleSave.
Verification (roam verify …)	Runs a suite of static checks on changed files: naming conventions, import validity, complexity, secret leaks, idiom‑pattern warnings, etc.	roam verify --auto (auto‑select checks for changed files) or more granular flags.
MCP server (roam-code[mcp])	Exposes the same queries over a network socket so an LLM‑based agent can call them as tools.	Install with pip install "roam-code[mcp]" and start the server; agents can then call roam commands via MCP.
Hooks for Claude Code (roam hooks claude)	Automatically injects pre‑execution context (callers, recent changes) into Claude Code prompts and verifies results after the model finishes.	roam hooks claude --write to enable, --uninstall to remove.
Roam Guard	A PR‑gate that records which checks ran, their outcomes, and can block merges if critical findings appear.	Use roam verify --auto in CI; the gate can be configured to fail on certain severities.
Performance	Indexing is a one‑time cost; subsequent refreshes are fast. Benchmarks (May–July 2026) show up to 80 % fewer LLM turns and large token/cost reductions for navigation‑type queries.	See the extensive benchmark tables in the README for exact numbers.

---

🚀 How you would typically adopt it

1. Add to a repo – pip install "roam-code[mcp]" inside the project’s virtual environment.
2. Create the index – roam init (first run may take a minute on large codebases).
3. Hook your agent – enable the MCP server or Claude‑specific hooks so the LLM can request roam data during its reasoning.
4. Run checks in CI – roam verify --auto (or a custom set of checks) to enforce a “gate” before merges.
5. Iterate – After a change, run roam preflight <symbol> to see the potential impact before committing.

---

📊 Why it matters for AI‑assisted development

• Local, privacy‑preserving – No API keys, no telemetry; the analysis stays on‑prem.
• Agent‑centric – Provides structured, symbol‑level context that LLMs can consume directly, cutting down the number of “search‑and‑open‑file” steps they normally need.
• Language‑agnostic – Supports 28 programming languages, making it useful for polyglot monorepos.
• Gate‑keeping – Can be part of a CI pipeline to prevent risky changes from being merged, complementing human code review.

---

📦 Quick start (four commands)

pip install "roam-code[mcp]"   # CLI + optional MCP server
cd /path/to/your/repo
roam init                       # build the index & config
roam health                     # see a health snapshot
roam preflight <symbol>         # assess risk before editing

---

TL;DR

roam‑code is a free, open‑source static‑analysis engine that turns a codebase into a searchable graph of symbols and their relationships. It lets LLM‑based coding agents ask precise, low‑token questions about the code, and it can enforce safety gates in CI—all without sending any source code off‑machine.