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 · zero API keys · zero network egress by default (opt-in metrics-push is the only outbound surface) · tamper-evident evidence

The decision tree

The agent contract covers the five rules and the canonical JSON envelope. 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.

Underneath every command is the same model: parse the repo once, store structural facts in a local SQLite index, and answer questions from that index. The output of each command lands as a JSON envelope; the audit pipeline composes those envelopes into typed ChangeEvidence packets that answer the eight evidence questions — who acted, what authority they had, what context was read, what changed, what could break, what policy applied, what verified it, and who accepted risk. See architecture for the compiler and Roam Audit for the analyst-driven projection of the same packets into a written report.

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. Cloud semantic reviewers (CodeRabbit, Greptile, Qodo, SonarQube) read the diff for naming and style; IDE surfaces (Cursor, Cody, Windsurf) log the session. Neither runs this algorithmic-shape class of check. Roam does, locally, before merge. See /compare for vendor positioning.

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?"

Roam compiles change-time evidence into typed ChangeEvidence packets that answer the eight evidence questions (who acted, what authority, what context, what changed, what could break, what policy, what verified it, who accepted risk). For governance work — SOC 2, ISO 42001, AI Governance — the same packet projects to a Code Graph Attestation (in-toto v1, optionally cosign-signed), a SARIF file for GitHub Code Scanning, and an OSCAL-shaped control mapping. The wording stays disciplined: Roam maps to and supports evidence for controls; it never certifies or makes compliant. See /docs/agent-contract for the canonical envelope, /docs/architecture for the compiler, and /audit for the analyst-driven Roam Audit projection.

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 vulns, roam taint) — 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 ingest-trace.

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 · read the architecture · run the 10-minute tutorial.

See it run: The 5-minute canonical demo — install → health → preflight → critique → signed ChangeEvidence packet, end to end.

Want the analyst-driven projection? Roam Audit replays your last five PRs through the same pipeline and returns a signed evidence packet plus a written report.