Skip to content
Back to search

revmux

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/umputun--revmux/badge.svg)](/listings/umputun--revmux)

HTML

<a href="/listings/umputun--revmux"><img src="/api/listings/umputun--revmux/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Homebrew, on macOS:

brew install umputun/apps/revmux

Prebuilt binaries for macOS and Linux, on amd64 and arm64, are attached to every [release](https://github.com/umputun/revmux/releases), along with `.deb` and `.rpm` packages:

dpkg -i revmux_<version>_linux_amd64.deb
rpm -i revmux_<version>_linux_amd64.rpm

With a Go toolchain, `go install github.com/umputun/revmux/app/revmux@latest` builds it from source into `GOBIN` (defaults to `$(go env GOPATH)/bin`). Or build from a clone:

git clone https://github.com/umputun/revmux.git && cd revmux
make build        # produces .bin/revmux
make install      # and symlinks it to /usr/local/bin/revmux

`make install` links rather than copies, so a later `make build` is picked up without reinstalling. Override the location with `BINDIR` when `/usr/local/bin` is not writable. `make uninstall` removes the link.

**Then install the skill, which is what asks for a review.** The binary runs one; the skill is how your coding agent drives it:

# Claude Code
claude plugin marketplace add umputun/revmux
claude plugin install revmux@revmux

# Codex
codex plugin marketplace add umputun/revmux
codex plugin add revmux@revmux

Install the skill through one marketplace only. If you previously copied or symlinked the Codex skill into `~/.codex/skills/revmux`, remove that copy after installing the plugin. Then ask for a review in words: revmux this branch, revmux pr 123, re-review after fixes. See [Agent skills](#agent-skills) for what it does.

revmux drives the model CLIs as subprocesses, so whichever ones your profile names must already be installed and authenticated: both for `comprehensive`, `focused`, `final`, `grill-me`, `triage` and `expert`, claude alone for `claude-only`, codex alone for `codex-only`. `preflight.sh` in the shipped skill answers it for any profile and any invocation.

`ANTHROPIC_API_KEY` is stripped from the child environment by default so `claude` uses interactive subscription auth; pass `--preserve-anthropic-api-key` if you authenticate by key. `claude` also runs with `--setting-sources project`, so your user `settings.json` is not loaded, and an `apiKeyHelper` set there never reaches the agents. Put the helper in the reviewed repo's `.claude/settings.json`, or put a `claude` wrapper first on PATH that runs the real binary, by absolute path, with `--settings <file>` added.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines
  1. {
  2. "name": "revmux",
  3. "owner": {
  4. "name": "umputun",
  5. "email": "umputun@gmail.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "revmux",
  10. "source": "./",
  11. "description": "Run a supervised multi-agent code review or triage a filed issue with parallel claude and codex subprocesses, and act on what comes back",
  12. "version": "0.5.6",
  13. "author": {
  14. "name": "umputun"
  15. }
  16. }
  17. ]
  18. }
README.md · README · 376 lines
  1. # revmux
  2. [![build](https://github.com/umputun/revmux/actions/workflows/ci.yml/badge.svg)](https://github.com/umputun/revmux/actions/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/umputun/revmux/badge.svg?branch=master)](https://coveralls.io/github/umputun/revmux?branch=master)
  3. **[revmux.com](https://revmux.com)** · [Documentation](https://revmux.com/docs) · [Reference](https://revmux.com/reference) · [Releases](https://github.com/umputun/revmux/releases)
  4. revmux runs a structured multi-agent review. It spawns and supervises `claude --print` and `codex exec`
  5. subprocesses, then returns findings on stdout as JSON or markdown.
  6. **It is normally launched by a coding agent rather than typed by you.** The [shipped skill](#agent-skills)
  7. works out what is under review, writes the context to disk, runs revmux and reads the report back. To that
  8. agent revmux is a black box with a stable contract, context in and a verified report out, which is why JSON
  9. is the default and `--markdown` is the opt-in for when a person is reading.
  10. **The subject does not have to be code.** A branch, a pull request, an implementation plan, a design document
  11. or a proposal all go in the same way. Triage is a job of its own: pointed at a filed issue or discussion, the
  12. `triage` profile runs a four-way panel over it, rating how much each point bears on the decision rather than
  13. what breaks at runtime, and returns the arguments for a maintainer to weigh instead of a verdict.
  14. revmux runs a review and returns findings, and does nothing else. It performs no scope detection, no git
  15. operations, no PR fetching and no source modification. All review context is written to disk by the caller
  16. and passed in as a task round, named with `--task` and `--run`.
  17. Full documentation is at **[revmux.com/docs](https://revmux.com/docs)**, and every flag, key and field is in
  18. the **[reference](https://revmux.com/reference)**.
  19. ![revmux running four agents, shown as a terminal overlay above the session that launched it](site/assets/screenshot-run.webp)
  20. A status table with one row per supervised process, a combined chronological pane and a tab per agent. The
  21. shipped launcher opens it in a terminal overlay, because an agent's shell has no tty.
  22. ## Why
  23. **Every agent is visible, and every phase recoverable.** Each model runs as a subprocess revmux owns, so it
  24. can be watched, timed, killed and relaunched: a watchdog on each one, a live view of what it is doing and
  25. what it has spent, one automatic retry, and a run archive to debug a bad review afterwards. Fan-out driven
  26. from inside an AI coding session has none of that, and agents that go quiet for minutes cannot be recovered
  27. from there. A subprocess does not make the model faster; it makes the run something the caller can hold on
  28. to.
  29. **One review standard rather than one per session.** A review assembled ad hoc varies with the prompt, the
  30. context left in the session, and whatever the model decided to look at that time. Here the roster, the
  31. lenses, the severity bar and the three stages are files, so two runs of a profile ask the same questions of
  32. the code. Checked into `.revmux/`, they are versioned and diffable, and a contributor gets the review a
  33. maintainer would have run.
  34. **Use the right model for each role.** A broad bug pass, an adversarial second opinion, synthesis and
  35. verification can favor different models, effort levels, latency and cost. Each finder selects its own binary,
  36. model and effort, and synthesis and verification can override those choices separately. The resolved runner
  37. for every process is recorded in the run archive.
  38. **Auditable by agents, not only by people.** The archive keeps the composed prompt each agent received, the
  39. verbatim output each one returned, the findings after every stage, and revmux's own decisions about stalls
  40. and retries. A person reads the report; an agent can read the entire run and propose edits to the lens and
  41. profile text behind it.
  42. **Rounds stack.** Reviewing a branch or a PR is never one review; it is a review, some fixes, and another
  43. review. revmux keeps the rounds under one task and hands the earlier ones to every agent in the next, with an
  44. instruction to judge them independently rather than confirm them.
  45. ## Install
  46. Homebrew, on macOS:
  47. ```
  48. brew install umputun/apps/revmux
  49. ```
  50. Prebuilt binaries for macOS and Linux, on amd64 and arm64, are attached to every
  51. [release](https://github.com/umputun/revmux/releases), along with `.deb` and `.rpm` packages:
  52. ```
  53. dpkg -i revmux_<version>_linux_amd64.deb
  54. rpm -i revmux_<version>_linux_amd64.rpm
  55. ```
  56. With a Go toolchain, `go install github.com/umputun/revmux/app/revmux@latest` builds it from source into
  57. `GOBIN` (defaults to `$(go env GOPATH)/bin`). Or build from a clone:
  58. ```
  59. git clone https://github.com/umputun/revmux.git && cd revmux
  60. make build # produces .bin/revmux
  61. make install # and symlinks it to /usr/local/bin/revmux
  62. ```
  63. `make install` links rather than copies, so a later `make build` is picked up without reinstalling. Override
  64. the location with `BINDIR` when `/usr/local/bin` is not writable. `make uninstall` removes the link.
  65. **Then install the skill, which is what asks for a review.** The binary runs one; the skill is how your
  66. coding agent drives it:
  67. ```sh
  68. # Claude Code
  69. claude plugin marketplace add umputun/revmux
  70. claude plugin install revmux@revmux
  71. # Codex
  72. codex plugin marketplace add umputun/revmux
  73. codex plugin add revmux@revmux
  74. ```
  75. Install the skill through one marketplace only. If you previously copied or symlinked the Codex skill into
  76. `~/.codex/skills/revmux`, remove that copy after installing the plugin. Then ask for a review in words:
  77. revmux this branch, revmux pr 123, re-review after fixes. See [Agent skills](#agent-skills) for what it does.
  78. revmux drives the model CLIs as subprocesses, so whichever ones your profile names must already be installed
  79. and authenticated: both for `comprehensive`, `focused`, `final`, `grill-me`, `triage` and `expert`, claude
  80. alone for `claude-only`, codex alone for `codex-only`. `preflight.sh` in the shipped skill answers it for any
  81. profile and any invocation.
  82. `ANTHROPIC_API_KEY` is stripped from the child environment by default so `claude` uses interactive
  83. subscription auth; pass `--preserve-anthropic-api-key` if you authenticate by key.
  84. `claude` also runs with `--setting-sources project`, so your user `settings.json` is not loaded, and an
  85. `apiKeyHelper` set there never reaches the agents. Put the helper in the reviewed repo's
  86. `.claude/settings.json`, or put a `claude` wrapper first on PATH that runs the real binary, by absolute path,
  87. with `--settings <file>` added.
  88. ## Quick start
  89. `revmux new` creates the round and prints every path you write to, so nothing constructs a path by hand:
  90. ```console
  91. $ revmux new --task pr-123 --run 01-initial
  92. {
  93. "task_dir": "/abs/.revmux/tasks/pr-123",
  94. "task_file": "/abs/.revmux/tasks/pr-123/task.md",
  95. "round_dir": "/abs/.revmux/tasks/pr-123/01-initial",
  96. "input_dir": "/abs/.revmux/tasks/pr-123/01-initial/input",
  97. "scope": "/abs/.revmux/tasks/pr-123/01-initial/input/scope.md",
  98. "created": ["task_dir", "task_file", "round_dir", "input_dir"]
  99. }
  100. ```
  101. Take the `scope` path out of that payload rather than joining it yourself, write the scope into it, and run
  102. the review:
  103. ```
  104. scope=$(revmux new --task pr-123 --run 01-initial | jq -r .scope)
  105. cat > "$scope" <<'EOF'
  106. Review the changes on this branch against master.
  107. Diff command: git diff master...HEAD
  108. EOF
  109. revmux --task pr-123 --run 01-initial
  110. ```
  111. That runs the `comprehensive` profile, shows a live TUI, and writes the report to stdout as JSON. After
  112. fixing something, open a new round on the same task and revmux carries the earlier rounds into every prompt:
  113. ```
  114. revmux new --task pr-123 --run 02-after-fix # then write its own input/scope.md
  115. revmux --task pr-123 --run 02-after-fix > findings.json
  116. ```
  117. ## How it works
  118. Three fixed stages. Only the roster and the severity bar vary between review shapes, so everything else is
  119. configuration.
  120. 1. **find**. The profile's roster runs in parallel: several `claude` agents, each composing one or more
  121. lenses, plus a `codex` peer. Launch is staggered, agent 1 first and the rest released once it produces
  122. its first output. Each agent returns structured findings.
  123. 2. **synthesize**. One model call. It merges every source's findings, dedupes on `(file, line ±2)`, boosts
  124. confidence where distinct sources corroborate, and splits out open questions and pre-existing issues.
  125. It drops nothing: a single-source, low-confidence finding still reaches verify.
  126. 3. **verify**. Parallel agents grouped by directory. Each verifier sees only its own group, so it cannot
  127. anchor on a neighbouring finding. Every finding comes back with a verdict: confirmed, refined, rejected,
  128. immaterial or pre-existing.
  129. **Codex is a peer source, not a second pass.** It runs alongside the lens agents and its findings go through
  130. the same synthesis and verification. Ordering the two would mean the second reviewer sees the first's
  131. findings and anchors on them, which is exactly what the cross-source confidence boost assumes did not happen.
  132. **A source is a process.** The confidence boost counts distinct processes, never lenses. An agent carrying
  133. two lenses that flags the same issue under both is still one source: it cannot corroborate itself. revmux
  134. stamps the attribution itself once the output is parsed; no schema exposes it to the model.
  135. **Degrade, never abort.** A stalled or crashed **finder** is killed, retried once, and on a second failure
  136. marked degraded while the run continues. The report banner names the missing agent, and synthesis is told the
  137. real source count. A run where *every* source degraded is a tool error, not a clean empty report.
  138. Verification is single-attempt instead: a verifier that fails leaves its group `unverified` rather than being
  139. relaunched, and never drops the findings it was given.
  140. ## Task rounds
  141. Review context reaches revmux only as a task round the caller has filled. `--task` names a task under
  142. `--tasks-dir` (default `./.revmux/tasks`), and `--run` names one round inside it. Both names are
  143. caller-chosen and semantic; revmux allocates neither.
  144. ```
  145. <tasks-dir>/pr-123/ a task: one subject, reviewed over as many rounds as it takes
  146. ├── task.md optional; front matter identifying the task
  147. ├── 01-initial/ a round
  148. │ ├── input/ caller-written; the only channel this round's own context travels through
  149. │ │ ├── scope.md {{SCOPE}} required
  150. │ │ ├── goal.md {{GOAL}} optional
  151. │ │ ├── profile.md {{PROFILE}} optional; non-empty overrides ./.revmux/profile.md
  152. │ │ └── context/ {{CONTEXT}} optional directory
  153. │ └── ... revmux-written artifacts: manifest, prompts, stages, events, tees
  154. └── 02-after-fix/ the next round, with its own input/
  155. ```
  156. Variables expand to the **paths** of these files, never to their contents, so no prompt can be bloated by a
  157. large scope. Context belongs to the round rather than to the task, because round 2 reviews the fixes for what
  158. round 1 found. A round that has already run is an error rather than an overwrite.
  159. `profile.md` is the exception, because what it says is true of the repository rather than of one round. Put
  160. it in `./.revmux/profile.md` and every round without a non-empty override inherits it — `revmux config`
  161. reports the resolved path as `paths.profile_fallback`, and the bytes are copied into each round as
  162. `prompts/input-profile.md` so the archive records what actually calibrated it. Write a round's own
  163. `input/profile.md` only to hold that subject to a different bar. A non-empty round file wins outright.
  164. Every run writes its own artifacts into that round beside the caller's `input/`: `manifest.json` with the
  165. resolved roster and prompt provenance, the composed prompt each agent received, the findings after every
  166. stage, an `events.jsonl` of stalls and retries, and the verbatim output of every agent. That is what makes a
  167. review auditable without re-running it. [The archive layout](https://revmux.com/docs#archive) has the detail.
  168. ## Output
  169. The report goes to **stdout** as JSON, or as markdown with `--markdown`. The TUI renders to the tty and
  170. progress lines go to stderr, so `revmux --task pr-123 --run 02-after-fix > findings.json` works with the
  171. display running.
  172. ```json
  173. {
  174. "scope": {"task": "pr-123", "run": "02-after-fix", "scope_path": "..."},
  175. "sources": {
  176. "expected": 4, "reported": 3, "degraded": ["docs+tests"],
  177. "agents": [
  178. {"name": "bugs+impl", "lenses": ["bugs", "impl"], "executor": "claude",
  179. "requested_model": "opus", "actual_model": "claude-opus-5",
  180. "effort": "high", "tokens": 48210, "raised": 6, "degraded": false}
  181. ]
  182. },
  183. "findings": [
  184. {"id": "f1", "file": "app/pipeline/find.go", "line": 88, "end_line": 0,
  185. "severity": "major", "confidence": 90,
  186. "title": "…", "body": "…", "fix": "…",
  187. "sources": ["bugs+impl", "adversarial"], "lenses": ["bugs", "adversarial"],
  188. "verdict": "confirmed"}
  189. ],
  190. "open_questions": [], "pre_existing": [], "immaterial": [],
  191. "stats": {"duration_ms": 333000, "tokens": 184920, "stages": []}
  192. }
  193. ```
  194. `sources` holds **agent names** and is the only input to the confidence boost. `lenses` holds the lens names
  195. that raised the finding and is informational: it answers "why was this reported", never "how many
  196. independently agreed".
  197. | Code | Meaning |
  198. |---|---|
  199. | `0` | no findings above `--min-confidence` |
  200. | `1` | findings above `--min-confidence`, a normal outcome rather than a failure |
  201. | `2` | tool error: bad config, an unusable round, an unwritable artifact, or every source degraded |
  202. [Every field, verdict and exit condition](https://revmux.com/reference#json) is in the reference.
  203. ## Profiles
  204. A profile is roster front matter plus a body that is the shared preamble and severity bar. Every roster entry
  205. composes lenses, and one `model:` string selects the binary, the model and the effort together, so claude and
  206. codex mix inside one review.
  207. | profile | roster |
  208. |---|---|
  209. | `comprehensive` | `bugs+impl`, `arch+quality`, `docs+tests` on claude plus an adversarial codex peer |
  210. | `focused` | one `bugs` agent plus the codex peer, for a small or time-boxed change |
  211. | `final` | `bugs+impl` plus the codex peer, nothing below major reported |
  212. | `claude-only` | the same four lens splits on claude, for a machine with no codex |
  213. | `codex-only` | the same splits on codex, and synthesis and verify with them |
  214. | `grill-me` | two lens splits, each run once on claude and once on codex |
  215. | `expert` | two agents at xhigh, each carrying all eight code lenses |
  216. | `triage` | a four-way panel over a filed item rather than a diff |
  217. **The eight are starting points, not the menu.** A profile is a file under `prompts/profiles/`, so dropping
  218. `.revmux/prompts/profiles/release.md` into a project makes `--profile release` work with no registration step
  219. anywhere. Its roster can be as wide as you are willing to pay for, each entry carries whatever lenses the job
  220. needs, and any entry can leave the profile's model for its own. Lenses resolve the same way, so a roster
  221. naming `payments` picks up `.revmux/lenses/payments.md`, written by whoever knows what goes wrong in that
  222. code.
  223. ```yaml
  224. ---
  225. description: pre-release pass over the payment path
  226. model: claude/opus:high
  227. agents:
  228. - {name: money, lenses: [bugs, impl, payments], color: red}
  229. - {name: contracts, lenses: [architecture, docs], color: cyan}
  230. - {name: peer, lenses: [adversarial], model: codex/gpt-6.2-sol:xhigh}
  231. - {name: second, lenses: [bugs], model: codex/gpt-6.2-sol:high}
  232. stages:
  233. synthesis: claude/opus:high
  234. verify: claude/sonnet:low
  235. ---
  236. ```
  237. Prompt text resolves per file across three layers: `./.revmux/`, then `~/.config/revmux/`, then the
  238. defaults built into the binary. `revmux init` copies each prompt file down into `./.revmux/` from the layer
  239. that won it, so there is something local to edit, and writes the config from the shipped commented template
  240. rather than from what resolved. `--dump-defaults <dir>` extracts the embedded tree for a diff.
  241. **Checked in, `.revmux/` is the project's review standard.** What a project cares about, its conventions,
  242. what counts as major, the mistakes it keeps repeating, usually lives in a maintainer's head and reaches
  243. contributors one review comment at a time. Committed, it is versioned and diffable like the rest of the code:
  244. a contributor who clones the repository gets the review a maintainer would have run, a finding traces back to
  245. the lens text that raised it, and a review that missed something is fixed by editing a file, once.
  246. **`.revmux/` is also code.** A checked-in lens becomes the instructions a headless agent with a shell
  247. executes, so running revmux inside a repository trusts it the same way `.claude/` or a `Makefile` there does.
  248. Review it before reviewing a branch you did not write.
  249. The [profiles](https://revmux.com/docs#profiles) and [lenses](https://revmux.com/docs#lenses) sections cover
  250. the roster keys, the model grammar and what each of the thirteen lenses looks for.
  251. ## Subcommands
  252. All five print JSON on stdout and exit before any review starts.
  253. | command | does |
  254. |---|---|
  255. | `revmux config` | reports the resolved configuration: knobs with their precedence layer, every profile, lens and stage, and the task store |
  256. | `revmux new` | creates a task, a round and its `input/`, and prints every path plus which of them it created |
  257. | `revmux init` | copies each prompt file down from the layer that won it, reporting which one that was, and writes the config from the shipped template |
  258. | `revmux stats` | arithmetic over the archive: per agent, per lens, per stage and per task |
  259. | `revmux cleanup` | removes one named task and everything under it, the only command that deletes anything |
  260. ## Terminal UI
  261. A status table with one row per supervised process, a combined chronological pane and a tab per agent, then a
  262. findings browser when the report is in. `i` shows the inputs the round was pointed at. With `--no-tui`, or
  263. when the tty cannot be opened, the same events render as timestamped lines on stderr.
  264. ```
  265. 16:02:11 bugs+impl started [bugs, impl]
  266. 16:04:02 docs+tests retrying: agent docs+tests stalled
  267. 16:05:12 bugs+impl done, 6 findings
  268. 16:09:03 ── complete ──
  269. 16:09:03 6m52s, sources 4/4, degraded none
  270. 16:09:03 6 findings: 1 major, 5 minor
  271. ```
  272. [Keys and panes](https://revmux.com/docs#tui) are documented on the site.
  273. ## Agent skills
  274. revmux is built to be driven by a caller model, and this repository ships that caller as a skill for two
  275. harnesses. Ask for a review in words and the skill does the rest: it resolves what is being reviewed, runs the
  276. git commands, writes the round's `input/`, launches revmux, reads the JSON back, and opens a new round on the
  277. same task after fixes.
  278. | harness | location | install |
  279. |---|---|---|
  280. | Claude Code | `.claude-plugin/skills/revmux/` | `claude plugin marketplace add umputun/revmux` then `claude plugin install revmux@revmux` |
  281. | Codex CLI | `plugins/codex/skills/revmux/` | `codex plugin marketplace add umputun/revmux` then `codex plugin add revmux@revmux` |
  282. Both carry the same reference material and the same scripts: `preflight.sh` checks the binaries an invocation
  283. needs, `task-state.sh` reports what a task holds, `launch-revmux.sh` runs revmux with its TUI in a terminal
  284. overlay, and `analyze-corpus.py` reads the archive back as numbers about the review itself.
  285. ## Development
  286. ```
  287. make build # build .bin/revmux
  288. make install # symlink .bin/revmux into $BINDIR (default /usr/local/bin)
  289. make test # race detector plus coverage, mocks excluded
  290. make lint # golangci-lint plus shellcheck over the shipped scripts
  291. make fmt # gofmt and goimports
  292. ```
  293. No test spawns a real model. The executors are driven through a mocked `CommandRunner` against recorded CLI
  294. fixtures, the pipeline through mocked runners, and the TUI through synthetic bubbletea messages.
  295. ## License
  296. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.