Every flag, key and field

The terse version. The documentation explains why each of these behaves the way it does.

Flags #

flag	default	description
--task=<id>		name of the task directory holding the review context
--run=<name>		name for this round of the review
--lenses=<a,b>		lens set replacing the profile roster, as one agent
--workdir=<dir>	working directory	directory the review subprocesses run in
--min-confidence=<n>	0	drop findings below this confidence
--no-synthesis		skip the synthesis stage
--no-verify		skip the verification stage
--no-tui		disable the terminal UI
--markdown		write the report as markdown instead of JSON
--preserve-anthropic-api-key		pass `ANTHROPIC_API_KEY` to the model CLIs
--idle-timeout=<d>	2m	kill and retry an agent after this long with no output. Also a config key
--hard-timeout=<d>	20m	kill an agent after this long, per attempt. Also a config key
--stagger-delay=<d>	30s	how long to wait for the first agent before releasing the rest. Also a config key
--max-parallel=<n>	4	how many agents run at once. Also a config key
--verify-groups=<n>	6	cap on the number of verifier groups. Also a config key
--verify-group-by=<k>	dir	`dir` or `source`. Also a config key
--tasks-dir=<dir>	./.revmux/tasks	root directory holding task directories. Also a config key
--auto-exit=<d>	0s	close the terminal UI this long after the report arrives; 0 never closes it. Also a config key
--profile=<name>	comprehensive	profile naming the roster to run. Also a config key
--config-dir=<dir>	~/.config/revmux	directory holding the config file and the prompt tree
--init		materialize the resolved prompt tree and a config template into `./.revmux/`
--dump-defaults=<dir>		extract the embedded prompt tree into a directory
--version		show version and exit

Config keys #

The nine runtime knobs above also read from ./.revmux/config and ~/.config/revmux/config, under the same name as the flag, in INI format. Command line wins, then project, then user, then the default, merged per key. Every other flag is command line only.

key	default	description
idle-timeout	2m	kill and retry an agent after this long with no output
hard-timeout	20m	kill an agent after this long, per attempt
stagger-delay	30s	how long to wait for the first agent before releasing the rest
max-parallel	4	how many agents run at once
verify-groups	6	cap on the number of verifier groups
verify-group-by	dir	`dir` or `source`
tasks-dir	./.revmux/tasks	root directory holding task directories
auto-exit	0s	close the terminal UI this long after the report arrives; 0 never closes it
profile	comprehensive	profile naming the roster to run

--task and --run are not config keys: a config file naming the round to write would make the same command review different context in different directories.

Subcommands #

All print JSON on stdout and exit before any review starts. None of them ever exits 1.

command	does
revmux config	reports the resolved configuration: knobs with their precedence layer, every profile with its roster and stage runners, every lens and stage description, the executor and effort vocabularies, and the task store
revmux new	creates a task, a commented-out `task.md`, a round and its `input/`, and prints every path plus a `created` list. Never overwrites
revmux init	materializes each prompt file into `./.revmux/` from the layer that won it, reporting which one that was, and writes the config from the shipped commented template rather than from what resolved. `--init` is the same thing behind a flag
revmux stats	arithmetic over the archive: per agent, per lens, per stage and per task. Reads only, and accepts an optional `--task`
revmux cleanup	removes one named task and everything under it. The only command that deletes anything

Environment #

variable	handling
ANTHROPIC_API_KEY	stripped from the child environment so `claude` uses interactive subscription auth. `--preserve-anthropic-api-key` passes it through
CLAUDECODE	always stripped: a `claude` child refuses to start when it thinks it is a nested session

Front matter #

key	accepted in	value
description	profile, stage, lens	a one-liner, reported by `revmux config`
model	profile, roster entry, stage, stage override	`<binary>[/<model>][:<effort>]`
lenses	roster entry	names of lens files, at least one
color	roster entry	an ANSI-16 name or `#RRGGBB`
stages	profile	`synthesis` and `verify`, each taking a model string
agents	profile	the roster, a list of entries

task.md

key	value
description	what this task is about, echoed by `revmux config` and `revmux stats`
url	the pull request, issue or page the task tracks
branch	the branch under review
base	what it is being compared against

All four are optional and are stored and reported, never resolved. revmux runs no git command against branch or base and fetches nothing from url.

Model string #

<binary>[/<model>][:<effort>]

claude                   claude, its own default model and effort
claude/opus:high         fully specified
codex/gpt-5.6-sol        effort falls back to the profile's, then the binary's
codex:high               codex's default model at high effort
claude/                  refused: a second spelling of `claude`
claude/opus:hgih         refused: not an effort

vocabulary	values
executors	`claude`, `codex`
efforts	`low`, `medium`, `high`, `xhigh`, `max`

Parses on the first / and the last :. A stage resolves through its stages: override, then the stage file's own model:, then the profile's. An entry naming a different binary than the profile brings its own model rather than inheriting one belonging to the other; effort carries across, since it belongs to neither model. Ask revmux config for what a given invocation resolves to.

Profiles #

profile	needs	roster
comprehensive	both	three claude lens splits plus an adversarial codex peer. The default
focused	both	one `bugs` agent plus the codex peer
final	both	`bugs+impl` plus the codex peer, nothing below major reported
claude-only	claude	the four lens splits on claude alone
codex-only	codex	the four lens splits on codex, both stages with them
grill-me	both	two lens splits, each run once on claude and once on codex
expert	both	two agents at the highest effort, each carrying all eight code lenses
triage	both	a four-way panel over a filed item; wants `--no-synthesis`

Lenses #

reviewing a change

lens	covers
bugs	correctness defects: logic and boundaries, nil and bounds, concurrency, resource lifetime, error handling
impl	goal fit: whether the change does what it set out to do, is wired up, and is proportionate
architecture	conventions and organization: the project's own rules, established patterns, dependency and interface shape
quality	style, over-engineering, error handling and accidental duplication in code that already works
docs	documentation accuracy: doc comments against the code, and the project docs the change leaves stale
tests	whether tests exist where a defect can hide, actually exercise the code, and survive concurrency
comments	the code's own stated rules: doc comments and inline notes the change was supposed to obey
adversarial	attacks the change looking for what a sympathetic reader would accept

reading a filed item

lens	covers
grounding	whether what a filed item claims is true of the code as it stands today
precedent	how comparable asks were decided here before, and whether that bears on this one
thesis	the strongest honest case that a filed item should be done or that its report is real
antithesis	the strongest case against, and whether something simpler reaches the same goal
cost	what implementing a filed item reaches into, and whether the work is proportionate

Prompt variables #

The vocabulary is closed. A prompt file naming anything else fails at load. Every context variable expands to a path, never to the file's contents.

variable	expands to	where
{{SCOPE}}	path of the round's `input/scope.md`	any prompt
{{GOAL}}	path of `input/goal.md`, or `none provided`	any prompt
{{PROFILE}}	path of `input/profile.md`, or `none provided`	any prompt
{{CONTEXT}}	path of `input/context/`, or `none provided`	any prompt
{{WORKDIR}}	the directory the subprocesses run in	any prompt
{{FINDINGS}}	the findings that stage receives	synthesis, verify
{{SOURCES}}	the true source roster, degrades included	synthesis only

Prior rounds are appended to every composed prompt as a block rather than a variable, because a variable would be opt-in per file and any prompt omitting it would silently lose the history.

Colors #

A roster entry's color sets its prefix color in both the TUI and the plain renderer, and is filled from a palette by roster position when omitted. Accepted values are the ANSI-16 names (red, bright-blue and so on) or #RRGGBB. An unknown value is a startup error.

Report JSON #

field	meaning
scope	`task`, `run` and `scope_path` for this round
sources.expected	how many sources the roster named
sources.reported	how many came back
sources.degraded	agent names that failed twice
sources.agents[]	per agent: lenses, executor, requested and actual model, effort, tokens, raised, degraded
findings[]	the report, filtered by `--min-confidence`
findings[].file	path relative to the working directory
findings[].line	the anchor; 0 means a file-level finding
findings[].end_line	optional; 0 means a single line
findings[].severity	how bad it is, calibrated by the profile's severity bar
findings[].confidence	0 to 100, boosted where distinct sources corroborate
findings[].title, body, fix	what it is, why, and what to do about it
findings[].sources	agent names. The only input to the confidence boost
findings[].lenses	the lens names that raised it. Informational, never a vote count
findings[].verdict	the verify stage's answer, see below
open_questions[]	what a reviewer could not settle from the code
pre_existing[]	real, but not introduced by this change
immaterial[]	true and not worth acting on
stats	timings, total tokens, and per-stage duration with the runner each resolved to

Empty lists are emitted as arrays rather than null. The three side arrays are not filtered by --min-confidence and do not affect the exit code.

Verdicts #

verdict	means
confirmed	checked against the code and it stands
refined	real, with the severity, the location or the claim corrected
rejected	does not hold; dropped from the report
immaterial	true and not worth acting on; moved to `immaterial`
pre_existing	real but not introduced here; moved to `pre_existing`
unverified	nobody checked it: the stage was skipped with `--no-verify`, its verifier group failed, or the model returned no usable verdict for it

Exit codes #

code	meaning
0	no findings above `--min-confidence`
1	findings above `--min-confidence`. A normal outcome
2	tool error: bad config, unreadable prompt tree, an omitted `--run`, a round with no `input/` or an empty `scope.md`, a round that already ran or is being written by another run, an unwritable artifact, every source degraded, or a delivered `SIGINT` or `SIGTERM`

Task layout #

<tasks-dir>/<task>/
├── task.md              optional front matter about the task
└── <run>/               a round
    └── input/           caller-written
        ├── scope.md     required
        ├── goal.md      optional
        ├── profile.md   optional
        └── context/     optional directory

Take these paths from revmux new rather than joining them: the layout is revmux's own detail, and a caller that reimplements it breaks silently when it changes.

Run archive #

<tasks-dir>/<task>/<run>/
├── manifest.json      resolved roster, prompt provenance and hashes, requested vs actual model,
│                      timings. Created empty as the run starts and filled in when it finishes,
│                      so it doubles as the marker claiming the round
├── prompts/agents/    the composed prompt each agent received, post-substitution
├── prompts/stages/    synthesis and one file per verify group
├── stages/            1-found.json, 2-synthesized.json, 3-verified.json
├── events.jsonl       stalls, retries, degrades, stage transitions
├── agents/            verbatim tees: <agent>.jsonl, <agent>.log, <agent>.retry.jsonl
└── report.md, findings.json

A failed archive write fails the run. The one exception is a per-agent tee under agents/, which degrades that one source instead.

Name rules #

No path separator, no .., not absolute, not starting with a dot.
Containment is re-checked on the resolved path, because a symlink defeats the lexical test.
A round may not be called task.md.
Roster agent names carry the same rule, applied when the profile loads.
A task name for revmux cleanup must be one task directly under the tasks root: a path, a .., a round name or a typo is an error and nothing is removed.

TUI keys #

keys	action
`tab` `shift+tab` `←` `→` `h` `l`	switch pane
`1`-`9`, then a letter	focus that pane directly
`f`	jump to the findings browser
`i`	show the startup input snapshot, or return
`↑` `↓` `k` `j`	scroll
`pgup` `pgdn` `ctrl+b` `ctrl+f`	page
`home` `end` `g` `G`	top, bottom
`/`	filter findings
`esc`	leave the input viewer or a filter; never quits
`q`	quit, once the report is in
`ctrl+c`	quit, at any point