Skip to content

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.
Illustrative output. The numbers, symbol names, file paths, run ids, and timestamps below are illustrative fixtures — the shape of what these commands emit, not values from a real repo. The byte-stable `ChangeEvidence` packet you get on your own machine fills the same shape deterministically from your index. See /docs/agent-contract for the canonical JSON envelope.

## 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. The packet maps to and supports evidence for SOC 2, ISO 42001, and EU AI Act Article 12 controls — it never certifies or makes compliant. See /docs/agent-contract for the envelope schema and Roam Audit for the analyst-driven replay of the same packet into a written report.

## 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.

## Where to next

- The agent contract — the canonical JSON envelope every command emits, plus the five rules an agent should follow.
- How Roam thinks — nine workflow moments mapped to the right Roam commands for each.
- Architecture — the evidence-compiler model, the eight evidence questions, and how packets project to SARIF, in-toto, and OSCAL.
- Roam Audit — the analyst-driven projection: replay your last five PRs through this same pipeline and get a signed packet plus a written report.
- Using Roam via MCP — the cold-start envelope and canonical agent loop for Claude Code, Cursor, and Continue.