Code Review

Multi-model code review

!"$CLAUDE_PLUGIN_ROOT/scripts/probe.sh" 2>/dev/null || "$HOME/.claude/skills/multi/scripts/probe.sh" 2>/dev/null || ./.claude/skills/multi/scripts/probe.sh

Several models read the same code, and you decide what reaches the user. That is the whole idea: one model invents problems and walks past real ones, and you cannot tell which from a single report. Independent models disagree, and the disagreement is the signal.

You are the judge, not a dispatcher. The reviewers propose; they do not vote, and none of them gets the last word. When they conflict, open the code and decide.

This is normally reached at the end of a session — work is done, PR or push comes next. Act like it: the question is "is this ready", not "here are some observations".

$SCRIPTS below is whatever the probe printed as scripts-dir:.

If the line above reads Shell substitution failed instead of probe output, the session is in a git worktree and its shell gate refused the header — the plugin is fine and so are the backends. Run the probe yourself, as one plain command with nothing but the path: "$HOME/.claude/skills/multi/scripts/probe.sh" (or the same under $CLAUDE_PLUGIN_ROOT), and read scripts-dir: from that. The gate also refuses sh -c, bash <file>, ${VAR:-default} and loops, so keep every later command in that shape too.

The gate

From the probe lines above — they are already there, do not re-run it.

No second reviewer family → stop. This is multi-model review; without at least one non-Claude reviewer there is nothing here that a single-model review does not already do. The pipeline runs four as reviewers: Codex, OpenCode, OpenRouter (Claude Code driving a non-Claude model) and Gemini — any one of them satisfies the gate — but only if it is in the profile that will run (the default profile, or the one the user named): a configured backend the profile leaves out reviews nothing. If the profile has no configured non-Claude backend, say so and point at /multi:setup. Do not quietly deliver a one-model review wearing a multi-model label.

Anything else missing is a note, not a stop: no OpenCode, no ponytail, not a git repo (fine — then the target is files, not a diff). Name what was missing in the report and carry on.

Whatever is missing, point them at /multi:setup to connect it — it walks through this step by step and does not need them to know any of the above.

Decide what you are reviewing

Whatever the user named. A diff, a branch, two files, one function, a line range, a module nobody has touched in three years, the whole repository. There is no fixed vocabulary here and no menu — read what they wrote and work out what they mean, the way a colleague would.

When nothing was named, in this order:

1. What this session was about. If you just wrote or changed something, that is the target — you know which files, what the task was, where you were unsure, what you fixed blind. That is better than a diff, which in a dirty tree also holds debug leftovers and unrelated edits, and which misses the old code the change leans on.
2. The branch, if it is ahead of main and the tree is clean.
3. The uncommitted diff otherwise.

Ask only when the answer genuinely changes what gets reviewed and you cannot tell — dirty tree and they mentioned a PR, say. Never open with a questionnaire: this skill runs at the end of a session, sometimes inside an autonomous run, and three questions there are worse than a wrong guess you announced. Guess, say what you guessed, let them correct you.

Whatever you settle on, resolve it into concrete paths, or a concrete git range, before dispatching. Every reviewer must look at the same thing — otherwise "two of them agreed" means nothing, they just happened to read the same file. If the target is vague, resolve it and say what you resolved it to.

Say what you are about to do

Always, before launching anything. Short, then go — this is not a request for permission, and you do not wait for an answer:

Reviewing: <target, and where it came from — "what we just did", "branch vs main", "you asked for src/auth.py">
           <when $REPO is not the session's own checkout, show the resolved path so a wrong-tree review is caught before it runs>
Running now: Codex <effort> · OpenCode <model> · ponytail          <— or why one is missing
Then: <what decides the Claude spend>

When the probe printed config: built-in default, add one line the user can act on — this is the first time most people learn the lineup is theirs:

Reviewers come from the default profile (no config file yet) — `/multi:setup` shows the file and how to change who reviews.

When a config file exists, name the profile instead: "profile normal from your config.toml". Say it once per session, not on every round.

If they wanted something else they will say so, and interrupting is cheaper than an interrogation.

Launch everything free, immediately

Codex, OpenCode and the ponytail lens cost nothing per run and take 30–70 seconds wall clock. There is never a reason to hold them back or make them conditional on a mode. Start the two external ones in the background, both at once — OpenCode spends about a minute just warming up — and do everything else while they run.

RUN="$($SCRIPTS/run-dir.sh --slug <two-to-four words: the project and the job, e.g. skills-fixing-multi>)"

# The tree under review. Usually the session's own repo; set REVIEW_DIR to a
# path or a different worktree when THAT is the target. Resolve it once: cwd
# resets between these blocks, so without an explicit path the reviewers silently
# read the session checkout and can "agree" on an empty diff.
REPO="$(git -C "${REVIEW_DIR:-.}" rev-parse --show-toplevel)"

# Isolate. The reviewers run on a COPY of the work tree, never the live one:
# a Bash sub-agent or an opencode flipped to bash by a hostile repo config can
# run `git checkout -- .` and wipe uncommitted work, and the copy takes that hit
# instead. The copy also drops the repo's opencode config, so a hostile
# .opencode/agent/plan.md cannot re-enable write+bash. It carries the diff as a
# file (review.diff) so nobody needs git in it — the copy has no .git. Pass the
# SAME --diff spec you review with; drop it for a
# whole-code (non-diff) review.
COPY="$($SCRIPTS/snapshot.sh --repo "$REPO" [--diff <spec>] [--paths "<paths>"] --dest "$RUN/snapshot")"
# If the snapshot failed (a typo'd --diff, a permission error, a --paths entry
# that is not in the copy), $COPY is empty and every reviewer would fall back to
# cwd — the live tree. STOP instead: that is the data-loss path this exists to
# close. Fix the target and re-run, don't review. Pass --paths whenever the
# target is named paths: the copy skips whatever git ignores, .git/info/exclude
# included, and the failure names the ignore rule — without --paths a folder
# hidden that way is simply absent and every reviewer agrees there is nothing
# to review.
[ -n "$COPY" ] || { echo "snapshot failed — not reviewing the live tree"; exit 1; }
# Snapshot ONCE. Persist the path so later blocks reuse this copy instead of
# re-running snapshot — a re-run rm -rf's and rebuilds the dir while the
# background ask.sh (and the sub-agents) are still reading it.
echo "$COPY" > "$RUN/copy-path"

# collect-context reads the ORIGINAL, not the copy: it only reads, and it needs
# the .git the copy does not carry to decide which rule files the change touched.
$SCRIPTS/collect-context.sh --repo "$REPO" [--diff <spec>] [--paths "<paths>"] > "$RUN/ctx.md"

# Everything that a reviewer executes points at $COPY. With --diff, add
# --diff-artifact review.diff so the prompt hands them the diff file instead of a
# git command that would fail in the copy.
$SCRIPTS/review-prompt.sh --repo "$COPY" --target "<in words>" [--diff <spec> --diff-artifact review.diff] [--paths "<paths>"] \
                          [--focus "<user text>"] --context "$RUN/ctx.md" > "$RUN/review.prompt.md"
$SCRIPTS/ask.sh --repo "$COPY" --question-file "$RUN/review.prompt.md" --out-prefix "$RUN/review" \
                --effort <low|medium|high|xhigh|max> --timeout "${MULTI_REVIEW_TIMEOUT:-2400}" \
                > "$RUN/ask.log" 2>&1

Run that last command as a background task (the Bash tool's run_in_background) — never in the foreground: a Bash call is capped at ten minutes, the review budget is forty, and a killed ask.sh takes every backend with it and marks them all KILLED.

One --out-prefix per target. A second review in the same session — another branch, a re-run with a different focus — gets its own ($RUN/review-2, $RUN/review-<branch>); ask.sh refuses a prefix whose backends are still running, because launching over them deletes the answers they are writing.

Waiting. A backend that has written nothing yet is not absent. Beside each answer file, <file>.running says <pid of its runner> <start epoch> <timeout> while the backend runs, and disappears when it is done; $RUN/review.run is the roster of the run. An empty .txt next to a live .running is a reviewer still writing — never report it as missing. Do not poll files by hand: block on them, and let a Bash call run up to its cap:

$SCRIPTS/wait.sh --prefix "$RUN/review" --max 540

It prints one line per backend — codex 5m12s ok, glm 23m04s ok, openrouter 9m30s still running (timeout 2400s), … FAILED: <the .dead text> — and exits 1 while something is still running: call it again. Exit 0 means everything has ended one way or the other, and the lines are the reviewer roster for the report. A free pool can take twenty minutes and still come back with the one finding nobody else had.

No --backend: who reviews is the default profile in the user's config.toml (the probe printed its backends and profiles). Pass --backend <profile> or an explicit list only when the user asked for a specific set for this review.

run-dir.sh prints this session's own directory, /tmp/multi/<session>--<slug>, and creates it. Two sessions reviewing at once used to share fixed /tmp names and overwrite each other's files. Shell variables do not survive between commands, so repeat RUN= and REPO= in every later block that needs them. COPY is the exception: snapshot it once (above), then in later blocks read the persisted path back with COPY="$(cat "$RUN/copy-path")" — never re-run snapshot.sh, or you rebuild the copy out from under the reviewers already reading it. --slug only labels the directory the first time, so a different wording later still lands in the same place. Runs older than a week are swept, and the snapshot with them.

--diff is what makes it a change review; leave it off and the reviewers read the actual code instead, with old code fully in scope. --paths narrows hard for collect-context and the sub-agents' scope, but note the limit in a diff review: snapshot.sh puts the whole diff in review.diff, so there --paths reaches the reviewers as a focus instruction, not a hard cut — do not rely on it to withhold a path from them. --target is always required — it is the human sentence, and it is what keeps the reviewers pointed at the same thing. --repo is the directory a backend works in: $REPO (the original) for collect-context, which only reads and needs the real .git; $COPY (the isolated snapshot) for review-prompt and ask.sh, and for the sub-agents. Snapshot the same --diff you review with, so the copy's review.diff matches the change.

The probe at the top of this file ran with no --repo, so its repo:, branch, dirty-file and ahead-of-main numbers describe the session checkout. When $REPO is a different worktree, those numbers are for the wrong tree — re-run $SCRIPTS/probe.sh --repo "$REPO" to orient on the real target before you trust them.

collect-context.sh gathers the repo's CLAUDE.md/AGENTS.md and the .claude/rules/*.md matching the target, and every reviewer gets it. This is what separates this from three models guessing: an external reviewer that does not know the project's settled decisions spends its findings re-litigating them.

The ponytail lens — invoke the ponytail:ponytail-review skill on the same target whenever the probe found it. It hunts one thing, over-engineering, and that keeps the defect reviewers out of matters of taste entirely (see below). Its findings are a different kind of thing and never mix with defects: they get their own section and cannot corroborate or contradict a bug. Invoking a skill loads it into you: the lens is your own read under a different ruleset, in a context that has already seen every other reviewer's findings — not a fourth independent reviewer. The report labels it that way; do not count it as one.

If ponytail mode is active, its SubagentStart hook injects the YAGNI ruleset into every sub-agent, including the ones hunting bugs. If findings start reading like simplification advice, that is why; PONYTAIL_SUBAGENT_MATCHER is the fix. Mention it once, move on.

Then decide how much Claude to spend

The external reviewers are free; your sub-agents are the user's money. So do not guess the depth up front — wait for the free results and decide on evidence. A two-line change both reviewers called clean does not need three sub-agents. A change where Codex reports two HIGH and OpenCode disagrees with one of them does.

Say the decision in one line when you make it: "going to normal — Codex found two HIGH, OpenCode contradicts one."

An explicitly named mode skips all of this. Obey it.

The adversarial pass needs Codex specifically; without it, ultra runs without that pass — the rest of the mode is unchanged.

Spawn them in parallel, in one message. Give each the target, the paths or range, the contents of $RUN/ctx.md, and the user's own words if there were any. Point them at $COPY, not $REPO — read the files in $COPY — and, only when you snapshotted a diff, add the change is in $COPY/review.diff (statuses in review.manifest). In a whole-code review (no --diff) there is no review.diff — do not point them at one that isn't there. Say once that line numbers come from the file, not from review.diff: a sub-agent that cites diff positions breaks the corroboration match against Codex and OpenRouter, who cite real lines. These reviewer agents have no Bash tool (they read with Read/Grep/Glob), so — unlike the CLI backends, which the copy sandboxes by running in it — they cannot run a destructive command against the live tree at all. That is the enforced half of the #14 fix: a sub-agent's shell would otherwise start in the session checkout, where a stray git checkout -- . wipes uncommitted work no matter what the prompt says. The copy still gives them the code and the diff to read; it just is not what protects the live tree from them — removing the shell is.

Model: the argument if given, else MULTI_REVIEWER_MODEL from the probe, else the agent files' default (Sonnet). No mode raises it on its own — ultra buys depth through more angles and real verification, not a bigger model.

ultra is not a deeper code review — it reviews whether the task got done. Was there a plan and was it followed; is the thing actually finished or only finished-looking; what was silently skipped; what will detonate later. That needs the task context — the plan, the spec, the conversation. Hand execution what you actually know about the job. Without any of that, ultra degrades to normal plus an architecture angle, and you should say so rather than pretend.

Judge

Normalize everything to {file, line, severity, claim}. Codex and OpenCode both answer the unified review prompt as FILE:LINE | HIGH|MEDIUM|LOW | reason, with repo-relative paths. OpenCode's file has two parts: ## <model> listing every tool call it made, then ## Answer with what it wrote in that unified format. Sub-agents report FILE:LINE | SEVERITY | confidence NN with two lines under it.

Read OpenCode's call list before its findings. It is there to answer one question: did this reviewer actually look at the code it is talking about? A finding about a file that never appears in the call list was invented, and it goes in Dropped. (none — this reviewer answered without opening anything) means the whole report is guesswork. NO ANSWER means it ran and said nothing: that reviewer was absent, say so as Codex/Opencode FAILED: <reason> from the one-line text in *.dead rather than reading silence as agreement. No answer file and no .dead at all, with nothing running, means the transport itself was killed before writing anything (KILLED is what a caught signal writes; a SIGKILL writes nothing, and leaves a stale <file>.running whose pid is gone) — that reviewer was absent too, say so. wait.sh tells these apart; an empty file beside a live .running is none of them, it is a reviewer still writing.

Inventory first, judge second. Before you merge, verify or drop anything, write out every finding every reviewer raised, one line each, with its author, its file:line and its claim in the reviewer's own words. Number them. One reviewer, one finding, one line — the inventory never groups authors ([Codex/GLM] is a bucket, not an inventory line), and a finding that names two mechanisms in one sentence ("X is unescaped, and the fallback returns raw text") is two lines. This is the list the rest of the report accounts for: every number lands in exactly one bucket below, and a number that appears nowhere is a finding you lost. Measured on real bugs: the judge's own failure mode is not inventing findings, it is folding two findings at the same place into one and keeping the wrong one — a reviewer's real bug merged with a neighbour's speculation and dropped with it. The inventory is what makes that impossible.

Then bucket. Two findings are the same only when they name the same mechanism — the same wrong line doing the same wrong thing. Same file, same function, even the same line with a different mechanism is two findings, and they stay two. When in doubt, keep them apart: a duplicate costs the reader one line, a merge costs them a bug.

• Corroborated — two or more reviewers from different families (Claude / Codex / OpenCode) named the same mechanism. Leads the report; independent agreement is the strongest evidence this pipeline produces.
• Single-source — one reviewer. Check each before the user sees it: open the cited lines, confirm it is real and reachable. In ultra, spawn one verify per finding instead and take its verdict.
• Minor — a real defect that is simply small. Not verified — that costs more than it is worth — and listed at the bottom, one line each.
• Dropped — only two things belong here: the code contradicts it, or (in a diff review) it predates the change. "Too small" is never a reason. A dropped finding keeps its own text and gets its own reason, and the reason cites the line that contradicts this finding — not a neighbour's. Two findings dropped for one reason is the merge above wearing a different hat.

Rules that make the report worth reading:

• Same scepticism for everyone. Codex being expensive does not make it right; the cheap reviewer being cheap does not make it wrong. In measurement here the cheap one caught a real bug Codex missed.
• Disagreements are surfaced, not averaged. Read the code, decide, and put the disagreement in the report — where good reviewers split is where the user should look.
• Nothing raised disappears silently. Every inventory number lands in a bucket, and a dropped one carries its own text and its own reason. Before you write the verdict, count: inventory numbers in, numbers placed — they match or you go back.
• Answer the user's own words first, if they gave any — even when the answer is "no, that path is fine, here is why".

Report

Report only: no edits, no commits, no PR comments. This is the default shape, not a schema — drop empty sections, and match the surrounding conversation.

# 🔍 Multi-review — <target> · <mode>
Reviewers: Claude <n> · Codex <effort> · OpenCode <model> · ponytail (lens: same judge, different ruleset)
<one line if something was missing or died, and why>

## 📋 Everything raised (<N>)
1. [Codex] `path/file.py:120` — <the reviewer's claim, one line>
2. [correctness] `path/file.py:120` — <a different mechanism at the same line stays its own number>
3. [OpenCode] `path/x.py:12` — …
<every finding from every reviewer, nothing merged yet; the buckets below cite these numbers>

## ✅ Corroborated (<n>)
1. **HIGH** `path/file.py:120` — <what is wrong> (#1, #4)
   <the concrete failure case> — Codex + correctness

## 🔸 Single-source, verified (<m>)
- **MEDIUM** `path/file.py:88` — <what is wrong> (#3) — [OpenCode] verified: <what you confirmed>

## ⚖️ Reviewers disagreed (<k>)
- `path/file.py:44` — Codex calls it a race (#5); correctness says the caller holds the lock (#11). <Your call, and why.>

## 🪒 Simplicity — ponytail lens, not an independent reviewer (<p>)
- `path/file.py:52-71` — delete: retry wrapper around an idempotent local call.

## 🔹 Minor (<q>)
- `path/file.py:12` — [correctness] log line interpolates the wrong id; misleads during an incident. (#8)

## ⚪ Dropped (<j>)
- #7 [Codex] `path/x.py:12` — <the finding's own claim> — pre-existing, not introduced by this change
- #9 [security] `path/y.py:40` — <its own claim> — `y.py:38` already escapes `name` before this line

## Verdict
<Ship it, or fix these first.> <If ultra: is the task actually done, and what is missing.>

Then stop. Offer to fix the top findings or to re-run deeper — do not do either unprompted.

Loop mode (opt-in) — fix, re-review, repeat

Only when explicitly asked ("loop", "until it's clean"). It edits the working tree; say so before the first edit if they were not explicit.

Each round: re-run the reviewers → take what survived judging → fix what is new → go again. Stop when a round brings nothing new, when only Minor is left, or at the cap (default 3). Never fix a dropped finding — silencing a false positive is worse than the finding. Never commit. After each round list what changed as file:line one-liners. If the cap is hit with findings open, say so.

Edge cases

• Huge target — say up front it will be slow and shallow, and offer a narrower one, rather than quietly reviewing four hundred files badly.
• Lockfiles, generated code, vendored trees — say so and skip the external reviewers; there is nothing there for them.
• A reviewer hangs — the caller passes --timeout "${MULTI_REVIEW_TIMEOUT:-2400}" to ask.sh; that value bounds each backend, and a failed run writes the reason as the one-line .dead text, so a hang arrives as ... FAILED: ..., never as an empty file. Treat that reviewer as absent and name it in the report. A reviewer still writing is alive, however long it takes — wait.sh shows how long it has been going and how much budget is left. Never block the whole review on one backend, but never write it off before its .running is gone either.
• OpenCode falls back to its free model — its output says so. Repeat it in the reviewer line; the user is entitled to know which model actually ran.