The Canonical Demo

Five commands, five minutes, one proof packet

This is the single screen-recording arc. No accounts. No API keys. No network egress. At the end you have a tamper-evident ChangeEvidence packet on disk that answers who acted, what authority existed, what was read, what changed, what could break, what policy applied, what verified it, who accepted risk.

Every command on this page runs against the developer's own machine. There is no cloud step. The same recording works on an air-gapped repo, a corporate laptop with no LLM token, or a CI runner with egress disabled. If a step prints output that reaches a server, it's a bug — please file it.

Step 1 — Install and index. Zero accounts, runs offline.

pip install "roam-code[mcp]"
cd /path/to/your/repo
roam init

Expected output excerpt:

VERDICT: indexed 25,954 symbols across 28 languages in 31.4s
.roam/index.db ready  |  fitness rules installed  |  CI workflow scaffolded

What this proves about the moat. Credential-free + zero-egress. You did not create an account, paste an API key, or accept a vendor's terms of service. Indexing parses your source tree with tree-sitter into a local SQLite database under .roam/. Nothing left the machine. The same step works behind a corporate firewall, on an air-gapped laptop, or inside a SCIF.

Step 2 — Score the repo. SARIF for CI, no cloud upload.

roam --sarif health > health.sarif

Expected output excerpt:

$ cat health.sarif | head -8
{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [ { "tool": { "driver": { "name": "roam", "version": "13.2", ... } } ... ] }

$ roam health   # human-readable verdict
VERDICT: Fair codebase (70/100) — 47 critical, 9 warnings, focus: god_components
Health Score: 70/100  |  Tangle: 0.1% (13/25954 symbols in cycles)

What this proves about the moat. CI-ready + zero-egress. The same composite score (complexity, cycles, dark-matter coupling, dead code, layer drift) that drives a buyer's PR-replay artifact also ships as SARIF 2.1.0 — the format GitHub Code Scanning, GitLab, and Defender for DevOps consume natively. No SaaS dashboard fee, no scanner-noise surcharge, no "your source is in our cloud now" step. The file is local; uploading it is the user's choice.

Step 3 — Gate the change. Blast radius before edit.

roam preflight ensure_index

Expected output excerpt:

VERDICT: Significant risk — CRITICAL, 608 symbols in blast radius

Pre-flight check for `ensure_index (src/roam/commands/resolve.py:154)`:
  Blast radius:     608 symbols in 236 files                 [CRITICAL]
  Affected tests:   7 direct, 372 transitive, 1 colocated    [OK]
  Complexity:       cc=3, nest=2                             [LOW]
  Fitness:          2 rule(s) fail on sibling symbols        [WARNING]

  Overall risk: CRITICAL
  Risk driver:  blast radius (608 symbols in 236 files, CRITICAL)

What this proves about the moat. Structural understanding before the AI agent writes a line of code. Cloud IDE agents (Cursor, Cody, Windsurf) and cloud semantic reviewers (CodeRabbit, Greptile, Qodo) all read the diff after the change. Roam reads the graph before. The agent gets a single deterministic verdict — 608 symbols across 236 files transitively depend on this function — that lets it decide whether to proceed, expand its context window, or refuse the edit. The number comes from a real static call-graph walk, not an LLM estimate.

Step 4 — Make the edit, then critique the diff.

# <agent makes its edit to resolve.py>
git diff | roam critique

Expected output excerpt:

VERDICT: REVIEW — 1 high-severity finding, 3 medium

[1] clones-not-edited (HIGH)
    Edited: src/roam/commands/resolve.py:154 ensure_index
    Unedited siblings in clone class C-04:
      tests/test_performance.py:143   ensure_indexed (fixture)
      tests/test_performance.py:233   ensure_indexed (fixture)
    Hint: a fix to ensure_index may need the test fixtures to track.

[2] blast-radius-touched (MED): 608 symbols downstream of changed lines

What this proves about the moat. Structural critique no semantic reviewer ships. roam critique reads the diff as a graph mutation against the local index — clone siblings the agent didn't update, blast radius of the changed lines, intent vs. dark-matter coupling, fitness-rule violations. Exit code 5 on high severity, so CI gates without parsing markdown. Same SARIF projection as Step 2 if you want Code Scanning to surface it.

Step 5 — Emit the evidence packet, then verify the chain.

roam runs start --agent claude-code
roam mode safe_edit
roam pr-bundle init --intent "Harden ensure_index cold-start guard"
# <preflight + critique envelopes auto-collect under .roam/responses/>
roam pr-bundle emit --strict
roam runs end --with-pr-bundle-emit
roam audit-trail-verify

Expected output excerpt:

VERDICT: pr-bundle initialised at wip-ensure-index.json (intent=Harden ensure_index cold-start guard)
  state:            initialized
  affected symbols: 0
  risks:            0
  tests required:   0
...
VERDICT: bundle emitted — 4 envelopes folded, ChangeEvidence v1.0.0
  signed:           .roam/pr-bundles/wip-ensure-index.json  (4.2 KB)
  runs:             .roam/runs/run_20260516_a7f3b1/meta.json  (HMAC chain intact)

VERDICT: chain valid (18 records)
  path:    .roam/audit-trail.jsonl
  records: 18
  first:   2026-05-16T...
  last:    2026-05-16T...

What this proves about the moat. Tamper-evident ChangeEvidence + HMAC-chained run ledger. Every step the agent ran logged a structured envelope into the active run. pr-bundle emit compiles those envelopes plus the diff hash, mode, active permits, accepted risks, and tests-required into a single portable JSON packet. The ledger SHA-256-chains every entry — flipping a byte or splicing a record in the middle breaks the chain and surfaces the affected line. This is the artifact a CISO buyer or auditor sees: proof that the agent read the right context, was authorised to act, ran the right gates, and recorded the result. Cursor and Cody log the session; Roam emits the proof.

What you just produced

At the end of these five steps, your repo contains:

.roam/index.db — the local graph (25k+ symbols, no cloud copy)
health.sarif — SARIF 2.1.0 health score for CI
.roam/responses/<timestamp>-preflight.json — the gate envelope
.roam/responses/<timestamp>-critique.json — the structural review envelope
.roam/pr-bundles/<branch>.json — the signed ChangeEvidence packet (answers the eight evidence questions)
.roam/runs/<run_id>/events.jsonl — the HMAC-chained event ledger
.roam/audit-trail.jsonl — the global tamper-evident audit trail

None of these files were uploaded anywhere. Sharing one is an explicit user action — attach to a PR, paste into a ticket, hand to an auditor. The packet is portable, deterministic, and re-verifiable on any machine with roam installed.

The category this demo establishes

Every other code-assistance tool on the market today is either (a) a cloud-IDE agent that writes code while logging the session, or (b) a cloud semantic reviewer that reads the diff after the fact. Both require an account, an LLM endpoint, and source-code upload. Neither emits a portable signed evidence packet.

Roam is the third shape: local-CLI agent-assurance. The five-command arc above is the entire shape of the moat in one sitting. See the side-by-side comparison against Cursor, Cody, Windsurf, CodeRabbit, Greptile, Qodo, and SonarQube.