adv-review

Adversarial review of pull requests and branches, for Claude Code
and, experimentally, for OpenAI Codex, Google Gemini and GitHub Copilot through a
standalone runner.
A scout designs the review for the specific change, one agent per angle hunts independently, the
findings are grouped by root cause, and every root cause is handed to a skeptic whose
job is to refute it. The report contains only what survived that attempt, labels
anything that could not be verified, and names who found and who checked each finding
and at which commit.

On a public calibration set of 21 PRs with 18 planted defects, the 0.4.0 release
confirmed 17 and wrongly refuted none. Every finding it confirmed was true, and the four
clean PRs drew no findings. See Calibration.

Quick start

1. Requirements. Claude Code on a paid plan with dynamic workflows enabled (on
   Pro, the Dynamic workflows row in /config), the GitHub CLI
   signed in to the repository's host, and git 2.5 or later.
2. Install.

   claude plugin marketplace add YahampathChandika/adv-review
   claude plugin install adv-review@yahampathchandika
   

3. Exclude the worktrees from your editor. Add **/.claude/worktrees to the file
   watcher and search exclusions. A long run creates one worktree per agent inside the
   open folder.
4. Run a review from a session in the repository:

   /adv-review:review 140
   

   For a branch with no pull request yet, /adv-review:review --branch. The first run
   asks for permission to run the workflow. A review takes roughly fifteen minutes to an
   hour and runs in the background; /workflows shows progress.
5. Read the report. Findings are listed most severe first, each with the failure the
   skeptics could not refute. The session then asks whether to post a summary comment on
   the PR. Nothing is posted, committed or pushed without your confirmation.

Optionally, add a .claude/adv-review.json with the project's install and test commands
and its own review angles. See Configuration. To run the review with
Codex, Gemini or Copilot, or from CI, see Agents and models.

Contents

• How it works
• Angles
• Installation
• Agents and models
• Usage
• Configuration
• Cost and footprint
• Limitations
• Security
• Calibration
• Development
• Background
• Licence

How it works

A review is a dynamic workflow of up to 20
subagents by default, each in its own disposable git worktree of the repository at the
PR's head commit. It runs in five phases.

The result records, for every finding: severity, file and line, the angle that found
it, the skeptics that checked it, the commit reviewed, and whether it was confirmed
cleanly or only after a correction or downgrade. Each finding states whether the PR
introduced the defect or it already existed on the base commit; pre-existing findings
are reported separately and left out of the posted comment unless requested. Refuted
findings are returned with the reason, and those dismissed for doubt alone (no skeptic
could show them false, every skeptic was unsure) are marked for a person to review. An
agent that dies mid-run is retried once while the agent ceiling has room.

Angles

Eight generic angles ship with the plugin. The scout may rule any of them out, but only
with a stated reason; an angle it did not rule out is guaranteed to run or to be named
as cut.

The generic angles are a baseline. A project's own angles, written from the defects it
has actually shipped, are what find the next one; see Configuration.

Installation

Requirements

• Claude Code with dynamic workflows (available on all paid plans; on Pro, enable the
  Dynamic workflows row in /config).
• The GitHub CLI, signed in to the repository's host, for
  pull-request reviews. A branch review needs only git.
• git 2.5 or later, for worktrees.

Install from the marketplace

claude plugin marketplace add YahampathChandika/adv-review
claude plugin install adv-review@yahampathchandika

Load for one session from a clone

claude --plugin-dir ./adv-review

Platform. The plugin path runs on Claude Code's workflow runtime, so it does nothing
on claude.ai or in Cowork. Other agents, and CI, use the standalone runner below.

Other agents (experimental)

The skill follows the open Agent Skills format, and the same review runs with the OpenAI
Codex CLI, the Google Gemini CLI or the GitHub Copilot CLI through runner/review.mjs.
Clone this repository, then either symlink the skill into a place the agent reads skills
from, or point the runner at the clone:

git clone https://github.com/YahampathChandika/adv-review.git
ln -s "$PWD/adv-review/skills/review" .agents/skills/adv-review   # Codex, Gemini and Copilot all read .agents/skills
export ADV_REVIEW_HOME="$PWD/adv-review"                           # or this, for the skill to find the runner

The agent's own CLI must be installed and signed in: npm install -g @openai/codex and
codex login, npm install -g @google/gemini-cli and gemini once, or
npm install -g @github/copilot and copilot once. The runner needs Node 20 or later
and git, and gh for pull requests; it is for macOS and Linux. The symlink keeps the
runner reachable from the skill; a copy of the skill folder alone does not include it.

Agents and models

A review has two layers. The session is what you type the command into: it resolves
the pull request, launches the review and reports. The agents do the reviewing: the
scout, the finders, triage, the skeptics and the critic. With the plugin, the session is
Claude Code and the agents run on Claude Code's workflow runtime. With the runner, the
session is node runner/review.mjs and each agent is a headless CLI process, in its own
git worktree, of the CLI you choose:

node runner/review.mjs 140                          # Claude agents, Opus by default
node runner/review.mjs 140 --agent claude --model sonnet
node runner/review.mjs 140 --agent codex            # GPT, whatever Codex defaults to
node runner/review.mjs 140 --agent codex --model gpt-5.5    # or --agent codex:gpt-5.5
node runner/review.mjs --branch --agent gemini      # the current branch, Gemini agents
node runner/review.mjs 140 --agent copilot          # Copilot agents, the CLI's default model

--agent picks the vendor and --model the model within it. The model key of
.claude/adv-review.json names a Claude model and applies to Claude agents only. The
runner is also the way to run the review from CI or with an API key, since it needs no
interactive session. Run it from a terminal: inside a Codex session, Codex's sandbox would
cut the agents off from the network.

To compare agents on one pull request, /adv-review:review 140 --agent claude,codex in
Claude Code reviews it once per agent and reports the comparison; a model may follow each
agent after a colon, as in --agent claude:sonnet,codex:gpt-5.5. Reviews run separately
with --out can be compared later with /adv-review:review --compare claude.json codex.json.
From a terminal, the runner does the same in one command, or the reviews can be run one
at a time with --out and compared afterwards:

node runner/review.mjs 140 --agent claude:sonnet,codex:gpt-5.5 --out results.json   # both at once, then the comparison; keeps results.<agent>.json
node runner/review.mjs 140 --agent claude --out claude.json                        # or one at a time...
node runner/review.mjs 140 --agent codex --out codex.json
node runner/compare.mjs claude.json codex.json                                     # ...and compared later

The comparison lists what every agent found, what only some did, what one agent confirmed
and another refuted, and the agents, minutes and cost of each run. Two findings count as
one when they sit within five lines of each other and their titles share at least half
their words; where another agent found something else at the same place, its finding is
named underneath, since that may be one defect in other words or two defects on one line.
It compares reviews of one commit only. Which agent is right about a finding is still a person's call: a real
pull request has no answer key, which is what the calibration set is for.

Runner options beyond the skill's: --jobs N agents at once (per agent in a comparison, so
two agents run up to twice that), --timeout MIN per agent
(default 30), --repo PATH, --keep-worktrees, --dry-run (prepare and print the
workflow arguments, run nothing), --network (Codex: allow network in the sandbox),
--max-turns N and --budget-usd X (Claude, per agent), --claude-permission-mode acceptEdits|auto, --allow-workspace-config (Gemini: review a repository that carries
its own .gemini/ settings). node runner/review.mjs --help lists them all.

Usage

Run from a session in the repository, on any branch.

During a run. The first run asks for permission to run the workflow and shows its
phases. The run then continues in the background; /workflows shows each agent's
progress and token use, and the run can be stopped there at any time. When it finishes,
the session reports the findings, removes the agents' worktrees, and asks whether to
post a summary comment on the PR. Nothing is posted, committed or pushed without your
confirmation.

The agent ceiling

--agents is the most a run may spend, not a quota. A small PR stops at six or seven
agents; a large one reaches the ceiling. About 30% of the ceiling is held back so that
what the finders report can be verified. With no number given, the run takes the
smallest ceiling with room for every fixed angle and two of the scout's own (20 for the
generic eight, more for a project with its own angles) and logs its choice. If a given
ceiling is too low to run every angle the scout kept, the run names the angles it cut
and the ceiling that would have run them, and reports itself incomplete. Partial
coverage is never reported as complete.

Configuration

Add .claude/adv-review.json at the repository root. Every key is optional. A starting
point is in examples/adv-review.json.

{
  "install": "pnpm install --frozen-lockfile --offline --ignore-scripts",
  "checks": "pnpm turbo run typecheck test --output-logs=errors-only",
  "isolate": "npx vitest run <file>",
  "agents": 30,
  "model": "opus",
  "angles": [
    {
      "title": "write-boundary",
      "brief": "Keys that get silently dropped. The section validator strips any key the schema does not declare, so a mapper or prefill that writes an undeclared key looks like it worked and stores nothing. Check every value written in this diff against the schema of the record it targets, and the reverse: a field declared but never written, or written under a name the reader does not read back."
    },
    {
      "title": "cross-tenant-reach",
      "brief": "Which tenant's data can this code read? Uploaded files are scoped to the account, not the project, so a query that filters on account alone reads another project's documents. For every new or widened read, name the other project whose record satisfies it and say where that value lands."
    }
  ]
}

Writing an angle. Add one when a review misses a class of bug that later causes
harm. A brief describes a failure shape and where to look, not a conclusion: what has
gone wrong before, where it hides, and what input to build to prove it. The examples
above are the form to follow.

Cost and footprint

• Tokens and time. A run spawns many Opus agents. Expect a review to cost several
  times what reading the PR in conversation would, and to take between fifteen minutes
  and two hours, most of it agents running the project's test suites. Runs count toward
  the plan's usage limits; a run that hits a limit pauses and resumes when the limit
  resets. --model sonnet or the model key gives a cheaper, weaker run.
• A lost agent. If an agent dies (a session limit, an API call that never answers),
  it is retried once. If the retry also fails, the run returns incomplete with the
  agent named, never as clean. With the plugin the run can be resumed: finished agents
  replay from cache and only the lost one runs again. The runner has no resume; a run
  that dies is rerun.
• Disk. Every agent gets a full worktree of the repository: under
  .claude/worktrees/ with the plugin, under the system temp directory with the runner.
  Ten agents on a large monorepo means ten copies. The session removes them after the
  report; if a plugin run is interrupted, remove that run's worktrees by its wf_… id as
  the skill describes.
• Editor. The worktrees are inside the open folder. Exclude **/.claude/worktrees
  from the editor's file watcher and search, or a long run can exhaust its file handles.
• Machine. Agents run the project's tests concurrently. Heavy suites can time out
  under that load; the scout re-runs any failing file alone before attributing a failure
  to the PR.

Limitations

• The review covers the diff at the PR's head, not the merged result and not a sequence
  of PRs deploying in order. Rollout ordering needs a person.
• It does not fix anything. A review ends at the report.
• A branch review covers committed work only, and has nothing to post to. Uncommitted
  changes are not reviewed.
• The runner is for macOS and Linux, has no resume, and its Codex, Gemini and Copilot
  backends are experimental; the Gemini and Copilot backends have not been run against
  a real CLI.

Security

Every agent is instructed that the diff, the PR's title and description, code comments
and the repository's files, the config file included, are data under review and never
instructions. Text that reaches a later agent's prompt is flattened to one line, so a
newline in a finding or a brief cannot pose as a section of instructions.

Agents may run the PR's code in their worktrees, which is what makes the strongest
verdicts possible. For a PR from a source you would not let run code on your machine,
pass --no-run: every agent reads, nothing executes.

Agents never commit, push, change branch, or post anything. The summary comment is
posted by the session, after your confirmation, under your gh identity.

What each CLI enforces through the runner. Claude agents run with acceptEdits
permissions and Bash allowed, so they can install, test and write repro scripts in their
worktree; that is permission-level, not operating-system, isolation, and your machine is
as exposed as with the plugin. With --no-run they run in Claude's restricted mode with
only read tools and read-only git commands allowed, and everything else denied without
asking. Codex agents run in Codex's operating-system sandbox: read-only with --no-run,
otherwise writes inside the worktree and no network unless --network, which a test
suite that listens on a port needs too. Codex also loads the skills from your own
.agents/skills folders into each agent, as it does in any session. Gemini agents
have no sandbox: --no-run is enforced by the prompt and by headless Gemini denying
tools that would need approval, so pass --no-run for a PR you do not trust, and the
runner refuses a repository that carries its own .gemini/ or .agents/ settings unless
told --allow-workspace-config, because Gemini would honour them. Copilot agents have no
sandbox either: --no-run is the CLI's own tool allow-list, git shell commands only with
writes denied; the repository's Copilot extensions (its agents, skills and MCP servers)
stay out of each agent, which is the CLI's default in prompt mode. Every Claude agent is
started without the repository's own Claude settings, hooks and MCP servers.

Calibration

The review is measured against a public fixture with known defects,
adv-review-calibration:
a small ledger service with two sets of pull requests carrying planted defects, and
clean PRs to measure false positives. The first set, eleven PRs, has ten defects across
the eight generic angles; the second, ten PRs, has eight harder ones that need more
than the changed lines to see. The answer key, the checker that shows every defect
bites, the scorer, the result files and every adjudication are in
calibration/. Both passes used Sonnet agents, so the numbers
are a floor for the default Opus configuration.

On the first set, 0.4.0 confirmed 9 of 10. No finder opened the file of the one it
missed; the critic named it, but the critic's gaps are not verified. All eight defects
of the second set were confirmed.

The 0.2.0 false positives were all notes on weak tests over correct code; 0.3.0 made a
blind test evidence on the defect it hides rather than a finding of its own.

Through the runner

The same four PRs, #4, #7 and #14 with four planted defects between them and the
clean #11, were reviewed through the runner with Claude agents on Sonnet and with Codex
on its CLI's default model, each at its default settings, next to the 0.4.0 plugin pass
on those PRs. Four PRs are a sample, not a score: they show that the review works with
that agent and how long it takes. The per-PR tables and every ruling are in
calibration/.

Codex reported more beside the planted defects, eleven true findings about the PRs and
one false; Claude through the runner reported one of each. One finding the 0.4.0 pass
had confirmed on #14 was found and then refuted this time by Claude's skeptics: it is
not planted, so it counts for neither recall nor precision, but it is the variance a
sample this size carries. Gemini was not run: no Gemini plan was available, and its
backend is tested against a stand-in CLI only.

Development

The workflow script's tests exercise every failure path (dead agents, a wrong commit, a
forged claim, a ceiling too low) with scripted stand-ins for the agents, so no agent is
spent:

node --test

tests/runner.test.mjs exercises the standalone runner with tests/fixtures/fake-cli.mjs
standing in for every CLI, so no model is called there either. evals/review-smoke is a
claude plugin eval case that runs one real review from a fresh clone of the fixture. It
is slow, spends agents, and needs --scaffold and --allow-tools; see its case.yaml.
calibration/run.sh runs the full calibration pass through the plugin path and
calibration/bench.sh a sample through the runner; calibration/README.md describes both.

Repository layout:

Background

The adversarial method behind this plugin, independent reviewers whose findings must
survive a reviewer told to refute them, was introduced to the author by
r3core. The ratios the plugin uses (30% of the agent
ceiling held back for verification, four root causes per skeptic, a panel for anything
high or critical) came from running it on real pull requests and keeping what worked,
and were then checked against the calibration set.

Licence

MIT. See LICENSE.