revmux

name	revmux
description	Run a supervised multi-agent code review by composing a task directory and driving the revmux CLI, then report or act on the findings it returns. revmux spawns and watches parallel claude and codex subprocesses with stall detection, retry, per-agent progress and a full run archive; this skill is the caller that writes the review context, launches it, reads the JSON back, and re-runs it after fixes. It also triages a filed issue, proposal or discussion instead of a diff, running a four-way panel over it — grounding, the case for, the case against, and cost — and putting the maintainer's six answers to him with the arguments behind each. It also has a self mode that reads what past rounds produced and tells the user what the record says about the review itself — which stage is filtering, which lens rates hardest, whether rounds converge — then proposes one change to the local prompt text at a time, with the number behind it. It fetches a pull request into a throwaway worktree, reviews it there and cleans up after. Also answers questions about revmux itself — profiles, lenses, task directories, flags, the JSON shape, exit codes and the run archive. Activates on "revmux", "run revmux", "multi-agent review", "supervised review", "review with revmux", "revmux this branch", "revmux the last commit", "revmux pr 123", "revmux this PR", "review PR 123 with revmux", "run a revmux round", "re-review after fixes", "revmux it and show me", "revmux this, I want to watch", "run it visible", "show me the review", "triage this", "triage issue 123", "is this worth doing", "should we accept this", "should I close this", "revmux self", "self-improve revmux", "tune revmux", "revmux profiles", "revmux lenses", "what does revmux return", "revmux exit codes", "revmux task directory".
argument-hint	optional: what to review ("pr 123", "issue 123", a ref, a path), plus "show me" / "focused" / "final" / "triage" / "loop" / "lenses a,b"
allowed-tools	["Bash","Read","Edit","Write","Grep","Glob","Agent","AskUserQuestion","Monitor","TaskStop"]

revmux — supervised multi-agent code review

revmux spawns and supervises parallel claude --print and codex exec subprocesses, watches each for stalls, retries what hangs, and returns findings on stdout.

It does no scope detection, no git, no PR fetching, no source modification. This skill does that half.

this skill	revmux
resolve what is under review	supervise, stagger, retry, degrade
run git, gather context	compose and archive prompts
write scope.md, goal.md, context/	merge, dedupe, verify
choose profile, lenses, flags	return findings on stdout
read the JSON, present, fix, re-run	inject prior rounds

Activation triggers

• "revmux", "run revmux", "review with revmux"
• "multi-agent review", "supervised review", "parallel agent review"
• "revmux this branch", "revmux the last commit", "revmux the uncommitted changes"
• "revmux pr 123", "revmux this PR", a pull-request URL — the checkout half, references/pr.md
• "triage this", "triage issue 123", "is this worth doing", "should we accept this", "should I close this", an issue or discussion URL — the panel over a filed item, references/triage.md
• "another revmux round", "re-review after fixes"
• "show me", "I want to watch", "run it visible", "in an overlay" — the overlay form in Step 4, which puts the TUI on screen. Any of these with a review request means overlay; alone they are not a trigger
• "revmux loop", "loop it", "keep going until clean" — the review-fix loop, references/loop.md
• "revmux self", "self-improve revmux", "tune revmux" — the self mode below, which reviews nothing
• questions: "revmux profiles", "what lenses are there", "revmux exit codes"

Answering questions without running anything

If asked about revmux rather than for a review, answer from the references and do not launch a run.

• references/task-dir.md — the round's context files, task and run naming
• references/invocation.md — flags, profiles, lenses, overlay backends, config precedence
• references/output.md — JSON shape, verdicts, exit codes, run archive
• references/present.md — the shape of the turn the user answers: order, detail, decision block
• references/pr.md — fetching a pull request into a worktree, --workdir, cleanup
• references/triage.md — the panel over a filed item: what it fetches, its flags, the six answers
• references/loop.md — the autonomous review-fix loop, entered from Step 6

For anything about current configuration, run revmux config and read the answer. It reports what resolved including user overrides, runs no pipeline, and is always safe to call.

Non-negotiables

0. Every run ends on an answer the user can give. Presenting findings or arguments is the middle of the job, never the end of it. A turn that stops after the report has not finished. references/present.md is the shape of that turn — read it before writing one, whichever review shape ran. The question widget covers the lines directly above it, so what the reader needs in order to choose goes inside the question and never immediately above it. An option names what it acts on, never counts it: "covering the two majors" is unanswerable and "covering the uv gate in make test and the request_user_input gap" is not.

1. Exit 1 means findings were reported — a success. 0 none, 1 findings, 2 tool error. Never treat 1 as failure. Never re-run on it.

2. Run it in the background. A review takes 3-15 minutes. Redirect stdout to a file, wait for the completion notification. Do not poll, do not sleep-and-check. Applies to the overlay launcher too. Watching the round's event log is not polling — Step 4 arms it, and it speaks only when the run does.

3. Check sources.degraded before believing the findings. If expected != reported the review is partial. Say so. Never report "no findings" from a degraded run as "the code is clean".

4. .revmux/ in a repository is executable code. A checked-in .revmux/lenses/*.md becomes instructions a headless agent with a shell executes. Before reviewing untrusted code, either read .revmux/ first or run from outside the tree with explicit --workdir, --tasks-dir, --config-dir. A fetched pull request is already outside it — references/pr.md leaves the process in the user's own checkout and puts only --workdir in the branch, so the other two need no override.

5. Never 2>&1 into the report file. stdout is the report, stderr is progress. Merging them makes the JSON unparseable.

Workflow

Step 0: Preflight

${CLAUDE_SKILL_DIR}/scripts/preflight.sh [profile] [--lenses]

Checks revmux plus every binary the invocation needs. Exits 1 naming what is missing.

Pass the profile that will actually run. Which executors are needed comes from that profile's roster, and with no argument preflight checks the resolved default instead — so a run under a profile the default does not share a roster with is never checked at all, and degrades mid-review over a CLI that was missing the whole time. If the user named a profile in any form, resolve it to an exact name first — that is Step 3's rule, and nothing in it depends on the scope, so it can be applied here. A word passed through unresolved fails preflight as an unknown name. If he named none, run it bare and run it again once Step 3 has chosen one.

Pass --lenses when the run will use it. That flag replaces the roster with one agent on the profile's own base runner, so the binaries needed are that base plus the stages, and none of the roster's own. Checked as an ordinary run, a --lenses invocation can pass preflight and then have its only finder fail to launch; checked the other way round, an ordinary run can be refused over a binary it never touches.

If revmux is absent:

brew install umputun/apps/revmux                   # macOS
go install github.com/umputun/revmux/app@latest    # installs as 'app'; rename to 'revmux'
git clone https://github.com/umputun/revmux.git && cd revmux && make install

Step 0.5: Offer the project profile, once per repository

revmux config's paths.profile_fallback is ./.revmux/profile.md when the repo has one. Every round without its own input/profile.md inherits it, and nothing creates it — not revmux init, not this skill on its own. An empty field means every review here runs on generic calibration.

When it is empty, say so in one line and offer to write it. Only ever with the user's yes, and never from the diff: read the project's own rules — CLAUDE.md, AGENTS.md, CONTRIBUTING.md, docs/, the linter config — and write what the software is, what a real failure looks like there, the blast radius, the reporting bar, and which conventions are deliberate. A profile guessed from one change is the thing this file exists to replace.

Offer it once. If he declines, do not ask again in the session, and do not write a round-local input/profile.md instead — that wins over the project file and is exactly the substitution the round brief forbids.

Never on a fetched pull request or any tree that is not his: .revmux/ is checked-in configuration, so authoring one there commits a review standard to somebody else's repository.

Step 1: Resolve what is being reviewed

the user says	scope
nothing, on a feature branch	git diff <base>...HEAD
nothing, on master with uncommitted work	git diff and git diff --staged
nothing, on master and clean	git diff HEAD~1
"the last N commits"	git diff HEAD~N
"since "	git diff <ref>..HEAD
"pr 123", "this PR", a PR URL	references/pr.md — resolve, fetch into a worktree, review it there
"issue 123", "triage this", an issue or discussion URL	references/triage.md — the panel over a filed item, not a diff
a bare number, kind unnamed	probe pull request, then issue, then discussion — the first that resolves decides which of the two rows above applies
a path	that subtree, as a diff plus a read list

Two commands here, and no more git than this:

git branch --show-current && git status --short
git diff <range> --shortstat

The shortstat goes into the brief. It is one line in this session and it is the whole of step 1 for the subagent, which otherwise spends three to five git calls arriving at the same three numbers — and they are the numbers Step 4's announcement is built from either way. Everything past the scale is still the subagent's: the full diff, the file list, what is worth reading.

Two rows in the table above are not a single range, so the one command does not cover them. Uncommitted work on master is git diff --shortstat plus git diff --staged --shortstat, and the scale handed over is the two added together — a bare git diff --shortstat reports nothing at all when the work is fully staged. A path scope has no range: hand over the file count instead, or hand over nothing and say so. Do not hand a number the commands in scope.md contradict, since the brief makes it binding — "take the scale as given rather than measuring it again".

A pull request is a different shape, not a harder ref range. revmux fetches nothing and checks nothing out, so a PR has to be on disk before there is anything to review, and the checkout has to be removed afterwards. Read references/pr.md and follow it — it covers steps 1 through 4 for that case and hands back here at Step 5.

A filed item is not a change at all, so there is no range to measure and nothing for Step 2's brief to read: it reads a diff and returns a shortstat, and a triage has neither. references/triage.md replaces Step 2 entirely — it fetches the item, its thread and the author's history into context/, writes the round, and hands back here at Step 5. A bare number goes through the probe in the table above first; a number that turns out to be a pull request is pr.md, whatever the user called it.

Ask only when genuinely ambiguous — a feature branch with uncommitted work is the standard case. Use AskUserQuestion, here and at the headless-versus-overlay choice in Step 4. The question is always this session's, never a subagent's: a subagent cannot ask, and one that guesses reviews the wrong thing at full cost.

Step 2: Prepare the round — in a subagent

Everything between the resolved scope and a round ready to run is delegated: reading the diff, matching the task, opening the round, and writing its context files. That is a dozen tool calls and several screens of diff whose output answers nothing the user asked — and it buries the review it is preparing for.

It is also the wait the user sits through before the review starts, and the wait is generation. Measured over eight archived rounds it ran 65 to 156 seconds, and the wall-clock tracked output tokens at a flat rate across all eight — so what makes it slow is prose written and turns taken, not tool latency. The budgets and the prohibitions in the brief are load-bearing for that, not tidiness.

Expand every path before handing the brief over. The subagent does not have this skill loaded, so ${CLAUDE_SKILL_DIR} means nothing in its shell — substitute the resolved absolute path into the brief's text rather than passing the variable through, or its task-state.sh step silently runs nothing.

Say one line first, then spawn it: Preparing the round for <what is being reviewed>… — the subject in the user's own terms, "the branch against master", "PR 123", "the last 3 commits". Then nothing further until the subagent returns: a delegated step the user was told about reads as work in progress, while an unannounced pause reads as a stall.

Spawn one general-purpose agent. Hand it the resolved scope from Step 1 and this brief:

Prepare a revmux review round. Write files; change no source, run no review, commit nothing.

The scope is: <the row resolved in Step 1, with its ref range>, and its scale is <the shortstat Step 1 printed>. Take the scale as given rather than measuring it again. Exclusions the user has stated: <list them, or "none"> — write these under the scope's explicit exclusions. They are decisions already taken, and the diff cannot show you one.

1. Read the change: the diff for that range, once, and the file list. That is the whole of the exploration. Do not read source files in full, do not grep the tree, and do not run a further diff per directory — naming a file worth reading is the reviewing agent's instruction, not a claim to verify first, and the round exists because four of them are about to read it properly.
2. If this session handed you a task id, use it verbatim and go to step 3. Otherwise match an existing task before minting one — a second id for one subject runs as a first round with no history. revmux config | jq '.paths.tasks' lists them with id, description, url, branch, base and rounds. Match on url or branch exactly, failing that on description against the subject in hand, and reuse the matched id verbatim. Derive one only when nothing matches: pr-<number>, issue-<number>, a branch name with / replaced by -, since-<short-sha>, or wip-<branch>. No path separators, no .., no leading dot, not absolute.
3. Run <the absolute path this session resolved for scripts/task-state.sh> <task-id>. It takes the id as its one argument and exits 1 with a usage line without it. It validates the id and reports the task.md anchors, every round, and each round's input/ state — prepared (never reviewed), claimed (a review started and never finished) or ran. That is the inventory; do not ls the task or a round to confirm what it already told you.
4. Name the round NN-label — 01-initial, 02-after-fix, 03-final — with NN one past the highest already there, and do not mix vocabularies across rounds of one task. Then revmux new --task <id> --run <NN-label>, exactly as written and with no --help run before it. It prints the absolute path of every file to write plus which of them it created.
5. Write to those paths and no others. Never join a path, never create a directory the output did not name, and never write over an existing scope.md without reading it first. Every file below is bullets, paths and command blocks — never paragraphs of prose. Every agent in the roster reads them and then reads the diff itself, so anything the diff already says is length paid for twice, and writing it is most of what this round costs in wall-clock.
   • scope — required, and under 1500 characters. What changed, the commands to see it, its scale, which files to read in full, what to ignore. Write commands in plainest form: git diff master...HEAD, never git -c core.pager=cat diff ... — a leading option defeats the child's permission matching.
   • goal — optional, and under 1000 characters. What the change is for, plus a "this is correct only if…" list. When the round is the last one before the branch merges, make it the gate: say the round exists to answer whether anything in this diff should not ship, and name what qualifies — a defect in executable code, a change to a prompt, schema or shipped script that would make a later run wrong, or a contradiction that would mislead an agent executing the document. Say that finding nothing is a valid answer, or the round reads as owing findings and manufactures them.
   • profile — do not write it. What it holds is about the repository rather than this round, so it lives in ./.revmux/profile.md and revmux gives every round without a non-empty override the same one with nothing copied forward. You see the diff and the file list, which is not enough to state a repo's conventions, and a generated file here wins over the project's and silently replaces it. Write it only when the user says this subject needs a different bar than the repo's.
   • context — optional. Ticket text, design notes, commit list. Its path is reported but the directory is not created.
   • task_file — when created lists it, and also when it is already there but still the unfilled template with every anchor empty. Read it first either way. description, plus url, branch and base when known: that front matter is what the next session matches on, and a task.md left as the blank template is what makes the next session mint a duplicate id.
6. Stop at the last write. A failed write returns an error, so there is nothing to confirm afterwards — no ls, no diff, no second task-state.sh, no git status.

Do not read the previous round's scope.md, goal.md or context/. revmux injects every prior round into every composed prompt itself, so reading them buys nothing and anchors this round's scope on the last one's wording. No round's profile.md is read either: the project file revmux resolves is not one of these.

Return JSON only: {"task": "", "run": "", "round_dir": "", "scope_path": "", "wrote": [], "files_changed": 0, "insertions": 0, "deletions": 0, "areas": [], "notes": ""}. areas names the parts of the codebase the diff touches. Put anything that went wrong in notes and do not paper over it.

Read references/task-dir.md yourself only if the subagent reports something it could not resolve.

Nothing else moves into a subagent. The profile choice, the launch, the report and how it is presented all stay in this session — they are the decisions the user is waiting on, and a summary of a decision already made is not the same thing.

Check what comes back before launching. A missing round_dir or an empty wrote means no round is ready and the run would fail on a missing scope; fix that here rather than launching into it. The scale numbers are what Step 4's one-line announcement is built from.

Step 3: Choose profile and flags

profile	roster	when
comprehensive (default)	bugs+impl, arch+quality, docs+tests, codex peer	real change, real risk
focused	one bugs agent plus codex peer	small or time-boxed
final	bugs+impl plus codex peer, nothing below major	pre-merge
claude-only	the same four lens splits, all on claude	no codex available
codex-only	the same four lens splits on codex, and synthesis and verify with them	no claude available
grill-me	bugs+impl and architecture+quality, each once on claude and once on codex, all reading against the change	the user wants it torn apart
expert	two agents at the highest effort, codex gpt-5.6-sol:xhigh and claude fable:xhigh, each carrying all eight lenses	a plan, or a change nobody wants to get wrong. Slow and expensive; pick it when he says so, not by default
triage	facts (grounding + precedent), thesis, antithesis, cost on codex	a filed item rather than a diff; needs --no-synthesis --verify-group-by source, references/triage.md

Never choose expert on your own. It is two agents at xhigh each applying every lens, so it costs several times what comprehensive does, and no property of the subject justifies reaching for it — not a plan, not a large diff, not a risky one. Pick it only when the user asked for it in words, and say that is why. Every other profile reviews whatever it is pointed at, a plan included; expert's severity bar is simply written so a proposal reads as naturally as a diff.

A profile word is not a profile name. Map whatever the user said onto the profiles revmux config reports, matching the name first and the description second. revmux rejects an unknown --profile at load and never guesses, so resolving is this skill's job — passing his word through unresolved just fails the run.

the user says	profile
full, everything, deep, thorough, the works	comprehensive
short, quick, fast, light, small, time-boxed	focused
last, pre-merge, before merge, strict	final