Documentation

How Roam thinks.

Pick the right tool for the question. Each Roam command answers a specific engineering question — match the question to the command, not the other way around.

Nine moments in an engineering workflow · 208 commands · 137 MCP tools · 28 languages

The decision tree

The agent contract covers the five rules. This page goes deeper: nine moments that come up in real work, with the four-to-five Roam commands that answer each and one example invocation per moment. If you only remember the moment, you can find the command later.

1. "I'm new to this repo. What does it do?"

You've cloned a codebase you didn't write. Before reading any file, get the shape: layers, entry points, hot files, the few symbols everything else depends on. Roam answers with a landing-pad summary, a curated tour, and a one-page minimap that fits in an agent's context window.

Commands: roam understand · roam tour · roam map · roam minimap · roam describe. 

$ roam understand
$ roam tour
$ roam minimap --tokens 4000

2. "I have a task. What code should I read first?"

You have a feature, a bug, or a phrase like "trace login flow" or "where is the n+1?" You need ranked, budget-bounded spans — not a grep wall. Roam returns the spans that matter, ranked by PageRank, clone signal, runtime hotness, and lexical match.

Commands: roam context · roam retrieve · roam search-semantic · roam agent-context. 

$ roam retrieve "where does login validate sessions"
$ roam context UserService
$ roam agent-context --tokens 8000

3. "I'm about to edit X. What breaks?"

Before any edit, ask Roam for the blast radius: who calls this symbol transitively, which tests cover it, and what fitness rules guard the surrounding architecture. The answer tells you whether the change is local, regional, or cross-cutting.

Commands: roam preflight · roam impact · roam affected-tests · roam diff · roam guard. 

$ roam preflight AuthService
$ roam impact AuthService
$ roam affected-tests AuthService

4. "Did the agent miss something on this PR?"

The most common AI-PR failure is structural: the agent edited one of three near-identical implementations, or the patch touched a high-PageRank symbol without updating the callers. Roam reads the diff against the graph and surfaces those misses with a verdict line first.

Commands: roam critique · roam clones · roam pr-risk · roam pr-analyze. 

$ git diff main..HEAD | roam critique
$ roam pr-risk
$ roam clones --persist

5. "Is the agent's patch correct but slow?"

The differentiator. Tests pass; the patch will fail at scale. Roam detects the algorithmic shape: accidental O(n²) lookups, N+1 queries, regex compiled inside hot loops, repeated JSON parsing, missing indexes on hot tables, branching recursion without memoisation. CodeRabbit, Greptile, SonarQube, Semgrep do not run this class of check. Roam does.

Commands: roam math / roam algo · roam n1 · roam missing-index · roam hotspots. 

$ roam math
$ roam n1
$ roam hotspots --danger

6. "Is the architecture drifting?"

Layers blur. Cycles appear. Modules creep into each other. Roam reports topological layers, strongly-connected components, Louvain communities, hidden co-change coupling, and a 0–100 health score with the worst-offending edges named. Wire the fitness rules into CI to fail PRs that introduce new cycles.

Commands: roam layers · roam cycles · roam clusters · roam health · roam dark-matter · roam fitness. 

$ roam health
$ roam cycles
$ roam dark-matter
$ roam fitness --ci

7. "Can I refactor safely?"

Before any move, rename, extract, or delete: clone the graph, apply the transform in-memory, report what breaks. If the simulation passes, roam mutate applies the transform to source. roam plan-refactor emits a step-by-step plan with caller-update ordering so a junior agent can execute it without breaking the build.

Commands: roam simulate · roam mutate · roam safe-delete · roam closure · roam plan-refactor. 

$ roam simulate move PaymentService src/billing/
$ roam safe-delete LegacyAdapter
$ roam plan-refactor PaymentService

8. "Multiple agents are working in parallel — can they?"

Hand three agents the same repo and they collide on the same files. Roam partitions the graph into low-coupling clusters, assigns one cluster per agent, and emits a fleet plan with conflict-free file ownership and a recommended merge order.

Commands: roam fleet · roam partition · roam orchestrate · roam agent-plan. 

$ roam partition --agents 3
$ roam orchestrate --emit fleet.json
$ roam agent-plan --target claude

9. "Can we prove what was checked, signed, and gated?"

For governance, audit, and SOC 2 / ISO 42001 / AI Governance evidence: emit a Code Graph Attestation (in-toto v1, optionally cosign-signed) that records the index hash, the fitness gates that ran, and the verdict. SARIF output plugs straight into GitHub Code Scanning so findings live next to the PR.

Commands: roam attest · roam cga · roam audit-trail-export · roam audit-trail-verify · --sarif. 

$ roam attest --sign cosign
$ roam audit-trail-export --since 2026-01-01
$ roam health --sarif > health.sarif

What you don't ask Roam

Roam answers structural, graph-aware, and algorithmic-shape questions. It does not replace the tools that answer the rest. When the question is one of these, reach for the right tool — and check /compare for who does what.

  • Semantic correctness — does this function actually do what its name says, prose-level. Use an LLM reviewer (CodeRabbit, Greptile, Qodo) or a careful human.
  • Code style and formatting — line length, quote consistency, import order. Use a linter and formatter (Ruff, ESLint, Prettier, Black, gofmt).
  • Single-function security smells — string-concat SQL inside one function, hard-coded keys, unsafe deserialisation in isolation. Use a SAST tool (Semgrep, CodeQL, SonarQube). Roam complements these by showing whether the smell is reachable from an entry point (roam vuln) — but the smell catalogue is theirs.
  • Type errors — use the type checker (mypy, tsc, pyright).
  • Runtime profiling — Roam predicts algorithmic shape from the graph. To measure a real run, use a profiler (py-spy, perf, your APM) and feed traces back via roam runtime ingest.

The framing is complementary, never replacement. Roam plus a linter plus a SAST tool plus an LLM reviewer covers the surface; any one of them alone leaves a gap.

Where to next

Read the agent contract · browse the full command reference · run the 10-minute tutorial.