MMR Reference

What MMR is

Multi-Model Review runs your changes past several independent AI code reviewers ("channels"), then reconciles their findings into a single de-duplicated list and a verdict that gates the work. No channel ever sees another channel's output — agreement between them is what raises confidence, and disagreement is what surfaces ambiguity.

The core idea in five moves

1. Resolve a diff — from a PR, staged changes, a branch range, or a piped diff.
2. Dispatch channels — each channel is a separate subprocess given the same prompt, run in parallel and isolated packages/mmr/src/commands/review.ts:636.
3. Parse — each channel's raw output is parsed into a common Finding shape.
4. Reconcile — findings are grouped by a stable key, de-duplicated, and scored for agreement and confidence packages/mmr/src/core/reconciler.ts:43.
5. Verdict — a severity gate yields pass, degraded-pass, blocked, or needs-user-decision packages/mmr/src/types.ts:25.

End-to-end flow

A single mmr review … --sync run walks the whole pipeline. Channels fan out in parallel; everything converges at reconciliation.

Compensating passes (see Degraded mode below) are injected after the first dispatch round for any channel that was unavailable, then folded back into the same reconcile step.

The mmr review command

One command, several input modes. Pick the flag that matches your target; everything else is control and output options. Type in the box to filter the table.

Copy-paste commands by target

# PR review (full pipeline, JSON out)
mmr review --pr 123 --sync --format json

# Staged changes before commit
mmr review --staged --sync --format json

# All tracked uncommitted changes (no untracked)
git diff HEAD | mmr review --diff - --sync --format json

# Branch range
mmr review --base main --head "$BRANCH" --sync --format json

# A single file's current contents, as an "all-added" diff
(diff -u /dev/null path/to/file.ts || true) | mmr review --diff - --sync --format json

# Only specific channels (e.g. just grok + claude)
mmr review --pr 123 --channels grok claude --sync --format json

Other subcommands

# Capture a job_id from a review, then fold in an agent channel:
mmr reconcile "$JOB_ID" --channel superpowers --input findings.json

Channel architecture

A channel is pure config data — there is no per-channel code. The dispatcher runs whatever command the channel defines, hands it the prompt, and parses its output with the configured parser. Adding a channel is normally a .mmr.yaml edit, not a code change.

The channel config shape

channels:
  <name>:
    enabled: true                 # run by default?
    command: "codex exec"         # whitespace-split, spawned WITHOUT a shell
    flags: ["--ephemeral"]        # appended after the command tokens
    env: { KEY: value }           # extra environment
    prompt_delivery: stdin        # stdin (default) | prompt-file
    prompt_wrapper: "{{prompt}}"  # template wrapped around the prompt
    output_parser: default        # default | gemini | doc-conformance | {kind:…}
    stderr: capture               # capture | suppress | passthrough
    timeout: 300                  # seconds (falls back to defaults.timeout)
    auth: { check, timeout, failure_exit_codes, recovery }
    extends: base-channel         # inherit from another channel (≤4 levels)
    abstract: false               # template-only; never dispatched directly

Built-in channels

command: codex exec
flags: [--skip-git-repo-check, -s, read-only, --ephemeral]
auth.check: codex login status        # local file check (fast, 5s)
recovery: codex login
output_parser: default
stderr: suppress

command: gemini                       # NO -p: gemini reads stdin natively
flags: [--output-format, json]
env: { NO_BROWSER: "true" }
auth.check: NO_BROWSER=true gemini -p "respond with ok" -o json   # LLM round-trip, 20s
recovery: gemini -p "hello"
output_parser: gemini                 # unwraps { "response": "…" }
timeout: 360

command: claude -p
flags: [--output-format, json]
auth.check: claude -p "respond with ok"   # LLM round-trip, 20s
recovery: claude login
output_parser: default

command: grok
prompt_delivery: prompt-file
flags: [--prompt-file, "{{prompt_file}}", --output-format, json]
auth.check: grok models                # lists models / login state (no round-trip)
recovery: grok login
output_parser: { kind: unwrap-jsonpath, wrap: "$.text", then: default }

enabled: false                         # opt-in: runs up to 3 LLM calls (~3 min)
command: scaffold observe audit --profile=full --scope=all --output-mode=mmr-findings
output_parser: doc-conformance         # expects a JSON array of findings
timeout: 240

The dispatcher

• Isolation. Each channel is spawned as its own detached subprocess writing to its own output file; channels run in parallel and never share output.
• Prompt delivery. stdin mode pipes the prompt and closes stdin (avoids E2BIG on large diffs). prompt-file mode writes the prompt to <channel>.prompt.txt and substitutes {{prompt_file}} in the flags packages/mmr/src/core/dispatcher.ts:79.
• Timeout. A per-channel timer SIGKILLs the whole process group and marks the channel timeout.
• Command parsing. command is split on whitespace and spawned without a shell — so quoting/pipelines in command won't work; that's exactly why arg-only CLIs like grok use prompt_delivery rather than a shell shim.

Adding a new channel — where it's clean vs. hard-coded. Clean (config only): a new subprocess channel (command + flags + auth + output_parser), output reshaping via the unwrap-jsonpath or regex-findings parser kinds, disabling/timeout overrides, and pointing the compensator at a different channel — all pure .mmr.yaml. Needs code: a brand-new named parser must be registered in core/parser.ts packages/mmr/src/core/parser.ts:257; and the COMPENSATING_FOCUS map carries per-channel focus text (falls back gracefully if absent). HTTP-endpoint channels (kind: http) are already supported via dispatchHttpChannel — pure .mmr.yaml, no extra code packages/mmr/src/config/schema.ts:144.

Scaffold wrappers

Direct mmr review runs the built-in CLI channels. The scaffold run wrappers add orchestration on top.

Findings, reconciliation & verdicts

The Finding shape

Every channel's output parses into this common shape packages/mmr/src/types.ts:45.

{
  "id": "F-001",
  "category": "security",
  "severity": "P0",
  "location": "src/auth.ts:42",
  "description": "…",
  "suggestion": "…"
}

The location above (src/auth.ts:42) is illustrative. After reconciliation, each finding also carries confidence, sources[], agreement, a stable finding_key, a description_shingle (for fuzzy cross-round matching), and acknowledged packages/mmr/src/types.ts:54.

Stable identity (finding_key)

finding_key = sha1( normLocation | category | sha1(normDescription) | sha1(normSuggestion) )

Line numbers are stripped from the location and severity is excluded, so the same issue at P1 vs P2 collapses to one key packages/mmr/src/core/stable-id.ts:115. A character-5-gram shingle backs a Jaccard ≥ 0.7 fuzzy match. Intra-run, findings group by fuzzy shingle overlap packages/mmr/src/core/reconciler.ts:83; across rounds, the ack store reuses the same threshold so a re-worded finding still matches a prior ack packages/mmr/src/core/ack-store.ts:8.

Agreement & confidence

Agreement and confidence are derived per group during reconciliation packages/mmr/src/core/reconciler.ts:114.

The gate & the four verdicts

The gate passes when every unacknowledged finding is below the fix_threshold packages/mmr/src/core/reconciler.ts:229 (default P2 packages/mmr/src/config/defaults.ts:16). Severity tiers run P0 (highest) → P1 → P2 → P3 (lowest).

The verdict is derived from gate result + channel health, in this branch order: zero channels completed → needs-user-decision; else a failed gate → blocked; else some channels incomplete → degraded-pass; else pass packages/mmr/src/core/reconciler.ts:247. (The no-completed-channels case short-circuits first, so it outranks blocked.)

Degraded mode, compensation & auth

A channel is "degraded" when it's not_installed (no binary), auth_failed, timeout, skipped, or failed. The review doesn't stop — it compensates and tells you how to recover.

• Compensating pass. For each degraded external channel, a claude -p pass runs with that channel's focus area, labeled e.g. [compensating: Grok-equivalent]. These findings are single-source, low confidence. The compensator channel is configurable via defaults.compensator.channel.
• Auth recovery is surfaced, never silent.

Configuration (.mmr.yaml)

Config is layered: built-in defaults → ~/.mmr/config.yaml → project .mmr.yaml → CLI flags. Arrays replace; objects deep-merge.

version: 1
defaults:
  fix_threshold: P2          # gate severity
  timeout: 300               # default per-channel timeout (s)
  parallel: true
channels_disabled: ["grok"]  # opt OUT of a built-in (e.g. no grok installed)
channels:
  doc-conformance:
    enabled: true            # opt IN to a default-off channel
  # Bring-your-own model via channel inheritance:
  qwen-local:
    command: ollama run
    flags: ["qwen2.5-coder:32b", "--format", "json"]
    output_parser: { kind: unwrap-jsonpath, wrap: "$.response", then: default }
    auth: { check: "ollama list", timeout: 5, failure_exit_codes: [1], recovery: "ollama serve" }

• channels_disabled — skip these built-ins in the default dispatch (ignored when you pass an explicit --channels list).
• enabled: false — per-channel off switch (how doc-conformance ships).
• extends — inherit from another channel (≤ 4 levels, cycle-checked); child fields override the parent packages/mmr/src/config/loader.ts:145.
• fix_threshold — project gate; override per-run with --fix-threshold.