roam-code
Local code analysis and ready-to-run checks for coding agents.
Roam gives your agent a reusable codebase index, pattern findings, candidate algorithmic alternatives, and checks it can call as it works. It can investigate code and evaluate changes without building each analysis from scratch.
Runs on your machine · free and open source · no account or API key for local analysis · no automatic source-code or telemetry upload
288 commands · 259 MCP tools (17 in the default core preset) · 28 languages
Connect your agent · Try a task · Documentation · Explore the code map
Why Roam is different
Your agent can read code, reason about it, and run tools already. Roam adds reusable local analyses: query indexed connections between files and functions, inspect a detected pattern with a proposed alternative, or run a scoped check. The results give your agent something concrete to inspect, test, and build on.
Static checks use local compute, not model calls or a paid Roam API. Your
agent's model usage, including reading those results, is separate. Refresh the
index with roam index as the code changes.
Roam is useful before there is a defect or a patch: trace a dependency, compare an approach, or establish which checks a change will need. Agents use the tools; people set direction and decide what ships. It complements your editor, search, tests, security tools, and code review.
Connect your agent
You need Python 3.10+ and a Git repository. On Linux, macOS, or Windows:
pip install "roam-code[mcp]"
cd path/to/your/repo
roam init
Replace the path with your project. init builds the local index and creates
project configuration; use roam index if you want only the index. The first
run can download a parser and takes longer than a refresh.
Then choose your agent's setup guide. Connect through MCP (a standard way for agents to use tools), or let your agent call the CLI. Add the usage instructions to its project configuration; connecting tools alone does not make the agent use them.
Prefer an isolated installation? Use pipx install "roam-code[mcp]" or
uv tool install "roam-code[mcp]". If your agent only needs shell commands,
pip install roam-code is enough. Container setup and limits.
roam health
roam preflight <symbol>
Replace <symbol> with a function or class in your project; find it with
roam search <name>. Read the returned locations, findings and missing checks,
not just the score. The historical fresh-install transcript
shows a recorded example, not current measurements of your checkout.
Try a task
Start with code you know. Ask your agent to use Roam to find a function's definition and references, then inspect the returned locations together. Follow the first-result checklist to confirm the intended repository, connected tools, and any incomplete results.
| What you want to do | What Roam supplies | What the agent still does |
|---|---|---|
| Find where to start | An overview, definitions and indexed connections | Read the relevant source and check the connections |
| Evaluate an approach | Pattern findings with alternatives from the algorithm catalog | Check semantics, try a change, test and measure it |
| Check a change | Impact analysis, related-test guidance and configured check results | Run the required tests and report missing evidence |
For example, roam algo can pair repeated list searches with a set or lookup-table
alternative. That is a candidate, not a proven improvement: value types, updates,
ordering, duplicates and returned positions can change the answer. Check behavior
and measure performance before adopting it. For its MCP tool, choose the review
preset and restart the server; it is not in default core.
Findings are leads. Static connections can be incomplete; a suggested test list is not test coverage, and a good health score is not permission to merge. Read the evidence limits.
Core commands
Start with these five commands. Use understand, context, retrieve, preflight, and critique for everyday exploration and change review. You can discover the rest as you need them: 288 commands (281 canonical + 7 aliases) organised into 7 categories. An alias is another name for the same command; you do not need to memorize them. The remaining ~283 commands beyond those five are detail surface for specialised workflows — they are called by agents on demand, not memorised.
| Verb | What it does |
|---|---|
roam understand |
Get an overview of the project and where to start reading |
roam context <symbol> |
Read a definition alongside the code that calls it and the code it calls |
roam retrieve "<task>" |
Find useful code for a question such as “trace the login flow” |
roam preflight <symbol> |
See what a change could affect, including connected code and tests |
roam critique |
Review a patch for related code you may have missed; pipe in git diff. High-severity findings exit 5 |
The full surface spans 7 categories — Getting Started, Daily Workflow, Codebase Health, Architecture, Exploration, Reports & CI, and Refactoring. Run roam --help for the 5-verb core, roam --help-all for every command name, and roam surface --json for the machine-readable inventory. Every command accepts roam --json <cmd> for structured output and roam --sarif <cmd> for CI integration (SARIF 2.1.0, honoured by 39 commands).
Use the complete command index or the command reference with examples.
MCP Server
MCP lets an agent call Roam tools directly. Install with the [mcp] extra
above and follow the client-specific setup.
The server command is roam mcp; the client starts it for the intended project.
Default preset: core (17 tools: 16 core + roam_expand_toolset meta-tool).
Select a wider preset for a named task by setting ROAM_MCP_PRESET in the
server's environment and restarting it. roam_expand_toolset reports what is
available; it does not switch the running server. See presets and tool schemas.
When consuming results, check errors, partial_success, scan scope, freshness,
and any response handle before calling a check complete. Preserve useful partial
findings, but do not treat missing evidence as a clean result.
CLI evidence handling · MCP usage.
There are 8 selectable presets (core, review, refactor, debug, architecture, compliance, compile-curated, full).
Choose by the task; the preset guide explains their contents.
Core preset tools: roam_alerts, roam_ask, roam_batch_search, roam_coupling, roam_dead_code, roam_deps, roam_diagnose_issue, roam_fetch_handle, roam_file_info, roam_grep, roam_metrics, roam_prepare_change, roam_search_symbol, roam_taint, roam_understand, roam_uses.
roam_ask (CLI: roam ask) routes a supported question to a recipe from the
31-recipe registry. It is a deterministic dispatcher, not a model conversation.
The full 259-tool table with descriptions lives in docs/mcp-tools.md.
Which preset ships where. The Claude Code plugin selects core for a
smaller tool list. This repository's own .mcp.json selects full so agents
working on Roam can test the wider surface. The difference is intentional.
Integration with AI coding tools
Use the integration guides for supported clients and project instructions. Review generated instructions before adding them to an existing a