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

# Install the MMR review skill into the current project for one or all agent CLIs:
mmr skill install --platform cursor
mmr skill install --all --dry-run

# Turn a channel off / on without hand-editing YAML (writes channels.<name>.enabled):
mmr config disable grok      # not-installed channels record to ~/.mmr/config.yaml; --project to scope to repo
mmr config enable grok       # also clears any legacy channels_disabled entry
mmr config path              # show where config is read from and written to

mmr critique — the design peer

review judges a diff. critique judges a design: a design doc, a plan, or a pasted "problem + proposed solution". Use it before you build, when you want independent models to weigh an approach.

It is advisory and never gates. Once the input resolves it exits 0, whatever the critique says; only a usage error (missing or unreadable input) exits 1. There is no severity, no fix_threshold, and no verdict.

The report has three parts:

• Convergence — what the models independently agreed on. High signal.
• Divergence — where they genuinely split, each position paired with the crux that decides it.
• Synthesis — an editorial read that deliberately never picks a winner.

The synthesis pass is conditional, not guaranteed — it runs only when at least two items and two channels came back and the claude channel is installed and authenticated. Otherwise you get the deterministic report alone.

mmr critique docs/design.md --context repo
mmr critique - --focus "scaling" --lenses skeptic,pragmatist

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>:
    kind: subprocess              # subprocess (default) | http
    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
    cwd: "{{neutral_cwd}}"        # run from a neutral dir (strips project config)
    prompt_delivery: stdin        # stdin (default) | prompt-file
    prompt_wrapper: "{{prompt}}"  # template wrapped around the prompt
    output_parser: default        # default | default-last | gemini | doc-conformance | {kind:…}
                                  # (`gemini` the PARSER is still registered and
                                  #  usable by custom channels — only the gemini
                                  #  CHANNEL is retired)
    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
    required: false               # true ⇒ compensate even when not installed
    retired: false                # tombstone; forced off, never dispatched
    headers: { … }                # http channels only (warns on inline secrets)

An http channel swaps command/flags for endpoint, model, endpoint_convention: openai-chat, and an optional api_key_env (sent as Authorization: Bearer … unless api_key_header / api_key_prefix say otherwise) packages/mmr/src/config/schema.ts:178.

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: agy                          # Google's CLI reviewer (alias of antigravity)
# runs hardened: neutral cwd, --sandbox, auto-approve, real HOME
auth.check: agy -p "respond with ok"  # LLM round-trip, 20s
recovery: agy -p "hello"              # then open the printed Google OAuth URL
output_parser: default

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,
        --no-memory, --tools, web_search,web_fetch,
        --disallowed-tools, run_terminal_cmd, --no-subagents, --no-plan,
        --json-schema, "{{findings_schema}}"]
cwd: "{{neutral_cwd}}"                 # neutral cwd + neutral HOME (auth symlinked in)
auth.check: grok models                # lists models / login state (no round-trip)
recovery: grok login
output_parser:
  kind: unwrap-jsonpath
  wrap: "$.text"
  incomplete: { status_path: "$.stopReason", values: [Cancelled] }
  then: default-last                   # grok emits one object PER TURN — take the last

enabled: false                         # opt-in, like doc-conformance
command: opencode run
flags: [--pure]
cwd: "{{neutral_cwd}}"
env: { OPENCODE_PERMISSION: '{"*":"deny"}' }   # no OS sandbox flag — deny every tool
auth.check: printf "respond with ok" | opencode run --pure
recovery: opencode auth login
output_parser: default
timeout: 300

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

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 + how many channels actually reported, in this branch order packages/mmr/src/core/reconciler.ts:280:

1. zero channels completed → needs-user-decision
2. else a failed gate → blocked
3. else fewer than min_completed_channels completed → needs-user-decision
4. else some channels incomplete → degraded-pass
5. else → pass

Two further needs-user-decision outcomes short-circuit before any channel is dispatched:

• Round budget exhausted — --round N greater than the effective --max-rounds emits max_rounds_exceeded and exits 3.
• Untrusted config in the diff — see the trust callout at the end of this guide; exits 2.

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 tells you how to recover and, for transient degradation, compensates.

• Transient vs structural (mmr 2.0.0). auth_failed/timeout/failed are transient — the channel will come back, so a compensating pass runs. not_installed is structural — the CLI isn't on this machine and won't return without action, so MMR no longer compensates it by default (a one-line notice names it). Opt back in with --compensate-missing on the review, or mark the channel required: true. Run mmr doctor to see the classification and the fix, or mmr config disable <name> to silence it.
• Compensating pass. When it runs, a claude -p pass uses 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 (redacted), 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
  min_completed_channels: 2    # completion floor (below it → needs-user-decision)
  timeout: 300                 # default per-channel timeout (s)
  format: json                 # json | text | markdown
  parallel: true
  job_retention_days: 7        # used by `mmr jobs prune`
  loop_control:
    max_rounds_default: 5
  compensator:
    channel: claude            # who runs a compensating pass (default: claude -p)
review_criteria: ["…"]         # extra criteria added to every prompt (see "Calibrating findings")
templates:                     # named criteria presets, selected by --template
  security: { criteria: ["…"] }
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.

Calibrating findings with review_criteria

review_criteria lines are injected between the core prompt and the diff packages/mmr/src/core/prompt.ts:51, so every channel sees them. The most useful thing to put there is what not to spend a finding on.

The built-in criteria packages/mmr/templates/core-prompt.md:9 ask five questions that are all about what is missing. The severity definitions do gesture at likelihood — P1 is scoped to "normal usage" — but no level says what evidence of reachability a finding needs, or how to grade something reachable but rare. On an early-stage codebase that yields a long tail of correct-but-unreachable edge-case findings, and gives reviewers no way to recommend removing code. The block below adds the missing calibration; it does not replace the built-in severity semantics.

version: 1
review_criteria:
  - "Trust boundaries are exempt from every rule below. Any input crossing a public API, exported library surface, CLI argument, HTTP handler, webhook, deserializer, file or database read, or any other boundary an outside party controls, is reachable by definition — you do not need to find a caller for it. Never downgrade a security, data-loss, or data-corruption finding for lack of an in-repository caller."
  - "For internal code only: before reporting an unhandled input or state, name the caller, flag, config value, or documented contract that can produce it. If you cannot name one and it is not behind a trust boundary, do not report the finding."
  - "Grade severity by impact AND demonstrated likelihood. An internal state that is reachable but rare in current usage is P2 or P3, not P1. Trust-boundary findings are graded on impact alone and are never downgraded for rarity."
  - "Also report what is unnecessary, not only what is missing: an abstraction with a single caller, a config knob never varied, a hand-rolled helper the standard library already provides, defensive code for a state that cannot occur. Make the suggestion a deletion. Validation at a trust boundary is never unnecessary."
  - "Do not report missing tests for internal behavior that has no caller yet, or for a branch you could not show is reachable. Missing tests for trust-boundary handling are always in scope."

This changes what reviewers report and how they grade it. fix_threshold, the reconciliation logic and mmr ack are untouched — but that is not the same as "no effect on merges". A finding that goes unreported, or that lands below your threshold, stops blocking. That is the intent when the finding was noise, and it is why the trust-boundary exemption above is not optional.

Treat the block as a starting template, not a tuned setting. Do not validate a change to it by comparing one before run against one after run: MMR's run-to-run variance on an identical input is larger than most effects you would be looking for. Two consecutive baseline runs of the same PR through the same three channels, with no config change at all, returned 4 findings and then 1. To get a real answer, hold the diff and channel set fixed, repeat each condition many times, and compare the rate of findings you have labelled low-value against a rubric written down in advance.

Trust modes and the ratification gate

MMR classifies every run into one of three trust modes packages/mmr/src/core/trust-mode.ts:97:

On top of that, in base-ref mode, there is a ratification gate: if the diff under review itself adds or modifies .mmr.yaml, or touches .mmr/acks/, the run stops with needs-user-decision and exit 2 before any channel is dispatched — including before --dry-run packages/mmr/src/commands/review.ts:487. A human has to ratify the change:

That is the point: a PR cannot quietly reconfigure the reviewer that is reviewing it. Both flags print a warning to stderr when used.

The gate is keyed on having a trusted base ref (baseRef !== undefined), so it does not fire in untrusted-head or non-git mode. That is not a hole: in those modes the working-tree .mmr.yaml and project acks are not loaded at all unless you pass a --trust-project-* flag, so there is nothing for the diff to smuggle in. Base-ref mode is the only one that would otherwise honor them, which is why it is the one that stops and asks.