When Roam is installed in a repo, agents have a local code graph, a call-graph, dependency edges, runtime hot-paths, git history, and an algorithmic-pattern library — all queryable through deterministic CLI commands or MCP tools. The contract below turns those capabilities into a five-step discipline.
Each step is one command. Each maps to one engineering question agents commonly miss. Together they prevent the failure modes we see in agent-generated PRs: missed clones, broken tests, accidental O(n²), risky refactors, hidden coupling.
1. Before editing — ask for context
$ roam context <symbol-or-file>
Returns the exact files + line ranges to read before changing a
symbol, prioritised by callers, callees, and tests. Stops the
agent reading the wrong files or skipping the relevant ones.
Same data shape as roam preflight, but compact —
ideal for prompt-context.
2. Before deleting — ask for impact
$ roam impact <symbol>
Full blast radius via Personalised PageRank: who calls this
symbol, transitively, weighted by churn and runtime hotness.
If the answer surfaces a caller the agent didn't know about,
the deletion is unsafe. Pair with
roam safe-delete <symbol> for the binary verdict.
3. Before merging — ask for critique
$ git diff main..HEAD | roam critique
Patch-level structural review. Catches clones-not-edited
(the agent updated one of three near-identical implementations),
layer violations (the diff just imported HTTP into the domain
layer), and blast-radius spikes. Exits 5 on
BLOCK findings — wire into CI directly.
4. Before refactoring — simulate first
$ roam simulate move <symbol> <new-file> $ roam simulate extract <file> <line-range> $ roam simulate delete <symbol>
Clone the graph, apply the transform, report what breaks before
any source file changes. roam mutate applies the
transform after the simulation passes; roam plan-refactor
produces a step-by-step plan with caller-update ordering.
5. Before optimising — ask for algorithmic risk
$ roam math $ roam algo --confidence high
The differentiator. Detects code that is correct but computationally wrong — exactly the class of patterns agents ship that pass tests and fail at scale: nested-loop lookups becoming O(n²), N+1 queries, regex compiled inside hot loops, repeated JSON parsing, quadratic string concatenation, branching recursion without memoisation.
Pairs with roam n1, roam missing-index,
and roam hotspots for the full performance-shape
sweep.
The whole contract, in one block
# Before any edit $ roam context <target> # Before any deletion $ roam impact <target> $ roam safe-delete <target> # Before any merge $ git diff | roam critique # Before any refactor $ roam simulate <op> <target> $ roam plan-refactor <target> # Before any optimisation pass $ roam math $ roam hotspots --danger
Wire it into your agent
Roam ships a Model Context Protocol server and an auto-generated Claude Code skill. Setup is one command per editor — see /docs/integration-tutorials for Claude Code, Cursor, Codex, Gemini, and Amp.
Or run roam skill-generate --target claude to emit a
SKILL.md directly from the live capability registry — the agent
gets accurate, up-to-date instructions for every command without
you hand-writing the prompt.
The principle behind the contract
Every command in Roam should answer a real engineering question that an agent or reviewer would ask. If a command doesn't map to a clear question, it's hidden, marked experimental, or improved. The goal isn't fewer commands — it's a clearer mental model.
Five questions × five commands = the discipline. Everything else is specialisation on top.
Where to next
Ready to try Roam? Install the free CLI · or read the command reference for the full surface.