Skip to content

Documentation

# Local codebase intelligence,
wired into your agent.

Roam turns your repository into a local code graph, then uses it for retrieval, architecture maps, algorithmic judgment, pre-change gates, and post-change evidence. Nine guides walk you from `pip install` to `roam math`, `roam preflight`, an MCP-aware editor, a pre-merge gate, and an audit trail that hash-verifies offline.

Start the tutorial Command reference

Apache 2.0 · zero API keys · zero network egress by default (opt-in metrics-push is the only outbound surface) · tamper-evident evidence · Runs entirely on your machine

## Ten guides

Pick where you are. Each guide stands alone; together they take you from `pip install` to a CI pipeline that gates on structural review.

1. The 5-Minute Demo Five commands, five minutes: install → health → preflight → critique → signed `ChangeEvidence` packet. Credential-free, zero-egress, the moat arc in one sitting. Start here if you have five minutes. 2. Getting Started Install, index your repo, ask the first structural question, run a pre-merge check, plan parallel agent work, sign a Code Graph Attestation. ~10 minutes start to finish. 3. Integration Tutorials End-to-end MCP setup for Claude Code, Cursor, Gemini CLI, Codex CLI, and Amp (Sourcegraph). Per-platform commands and the cross-platform validation checklist. 4. Using Roam via MCP First-run setup, the cold-start envelope your agent sees on a fresh repo, the tools that work without an index, the canonical agent flow, slow-tool patterns, and the failure modes that trip up real users. 5. Command Reference The full command surface, grouped by intent: exploration, health, refactoring, security, governance. Each entry has flags, output, and a concrete usage example. 6. Architecture How the index pipeline, storage, graph engines, retrieval, and patch verifier fit together. The system diagram + subsystem responsibilities + command-to-data flow. 7. The Agent Contract Five rules an AI coding agent should follow when Roam is available — context before edit, impact before delete, critique before merge, simulate before refactor, math before optimise. The discipline that turns capabilities into outcomes. 8. How Roam thinks The decision tree. Nine moments in an engineering workflow, mapped to the four-to-five Roam commands that answer each. Match the question to the command, not the other way around. 9. What AI misses, Roam catches Eight concrete scenarios — clones, blast radius, accidental O(n²), N+1 queries, layer violations, missing tests, refactor safety, signed audit evidence — each with the exact command output Roam produces. Read this to feel what the tool does. 10. Troubleshooting Eight things that go wrong with Roam and the one command that usually fixes each — stale indexes, cloud-sync conflicts, missing extras, parser failures, MCP setup, cache permissions, OOM during indexing, slow JSON output.

## Need help getting started?

If your team would rather have a walkthrough than read four guides, email hello@roam-code.com and we'll set up a 30-min call. Free for the first 5 teams.