---
name: magpie-review
description: Run a multi-AI adversarial code review using the `magpie` CLI. Multiple AI models independently review the changes, debate findings, and a verifier audits each issue against the actual code. Use whenever the user asks for a "magpie review", a "multi-AI review", an "adversarial review", a "second opinion review", or wants magpie to look at local uncommitted changes, the current branch, or a GitHub PR. Also use when the user wants to `magpie discuss` a topic or do a whole-repo review.
---

# magpie-review

Wraps the `magpie` CLI to run adversarial multi-AI code reviews. Magpie spawns several reviewer models (Claude Code, Codex, Gemini, etc.) that independently review a change, debate across rounds, then a verifier audits each reported issue against the actual code.

## When to pick which mode

Magpie supports three review targets — pick based on what the user is reviewing:

| User's intent | Command |
|---|---|
| Review work I haven't committed yet (staged + unstaged) | `magpie review --local` |
| Review the commits on my current branch vs a base | `magpie review --branch [base]` (base defaults to `main`) |
| Review a GitHub PR | `magpie review <pr-number>` or `magpie review <pr-url>` |
| Review specific files only | `magpie review --files <path> [path...]` |
| Review the entire repository | `magpie review --repo` |
| Discuss a topic / design question | `magpie discuss "<topic>"` or `magpie discuss <path-to-file.md>` |

If the user is ambiguous (e.g. "review my changes"), check `git status` and `git log @{u}..HEAD` to figure out whether they mean uncommitted, committed-but-unpushed, or already-pushed work — then pick the matching mode rather than guessing.

## Running a review

Always run `magpie` from inside the target repo's working tree. For PR mode it uses the `origin` remote to find the repo by default.

### Common flags

These apply to both `review` and `discuss` unless noted:

- `-i, --interactive` — Pause between turns for Q&A. Use when the user wants to drive the review themselves.
- `-a, --all` — Use every configured reviewer without an interactive picker. Good for non-interactive/batch runs.
- `--reviewers <ids>` — Comma-separated reviewer IDs (e.g. `claude-code,gemini-cli`) when you want a specific subset.
- `-r, --rounds <n>` — Cap the debate rounds (default 5).
- `--no-converge` — Disable early-stop on consensus. Use when you want the full debate even if reviewers agree quickly.
- `-o, --output <file>` and `-f, --format <markdown|json>` — Save results to a file.
- `--fail-fast` — Abort the whole flow if any reviewer fails. Default is resilient (continues with surviving reviewers). Use fail-fast when debugging provider/auth issues or when the user wants a guarantee every reviewer participated.
- `--plan-only` — Generate the review plan without running reviewers. Useful for a quick preview of what magpie *would* do.

### `review`-only flags worth knowing

- `--skip-context` — Skip the context-gathering phase (call chains, related PRs). Faster, less informed.
- `--no-post` — Skip the post-debate GitHub comment-posting flow. Use in non-interactive contexts where you just want the review output, not the interactive post-each-issue loop.
- `--no-conclusion` — Skip the final summarizer. Useful for bot/CI use.
- `--git-remote <remote>` — Override the remote used for PR-URL detection (default `origin`).
- `--reanalyze` — Bypass the analyzer cache and re-analyze from scratch.

### Repo-mode flags (with `--repo`)

- `--path <subdir>` — Limit the repo review to a subdirectory.
- `--ignore <patterns...>` — Skip matching paths.
- `--quick` — Architecture overview only.
- `--deep` — Full analysis, no prompts.
- `--list-sessions` / `--session <id>` / `--export <file>` — Manage long-running repo review sessions (they persist so you can pause and resume).

## Interactive vs non-interactive

Magpie's default flow includes interactive prompts (reviewer selection, per-issue post/edit/skip after the debate). When you (Claude) are invoking magpie programmatically on the user's behalf:

- Prefer `-a` (or `--reviewers`) to skip the reviewer-selection prompt.
- Prefer `--no-post` to skip the per-issue posting loop — the user can still read the review output.
- If you want a clean machine-readable result, add `-f json -o <file>`.

When the user wants to drive the review themselves, hand the command back to them to run (e.g. via `! magpie review ...`) so they get the interactive UX rather than running it through a tool call.

## Running it as a long task (it takes minutes)

A full review runs several models across multiple debate rounds, so it takes minutes. Run it as a background `Bash` task with `run_in_background: true` and save the output (`-f markdown -o <file>`). The background task auto-notifies you when it completes — that completion notification is all you need; read the saved output file then.

- **Do not add a separate `Monitor` on the same output file.** The background task already notifies on completion, so a monitor watching the same file is redundant. Only add a `Monitor` if you genuinely need streamed interim progress, and even then it is usually unnecessary for a fire-and-forget review.
- **Never copy the output path by hand.** Pass the same explicit `-o <file>` path you chose (e.g. `/tmp/magpie-review.md`) to your follow-up `Read` — don't transcribe the long auto-generated task-output path from the completion notification, which is easy to typo.
- **Don't suppress stderr** (`2>/dev/null`) on magpie or on any watcher command. If something fails — bad path, auth error, missing reviewer — you want to see why, not a bare non-zero exit. Use `2>&1 | tee <log>` if you want both a saved log and visible errors.

## Examples

**User: "Have magpie look at what I'm working on right now."**
They likely mean uncommitted work. Run:
```
magpie review --local
```

**User: "Get a magpie review on this branch before I push."**
Current branch vs main:
```
magpie review --branch
```

**User: "Run magpie on PR 4521."**
```
magpie review 4521
```

**User: "Use magpie to review just the changes to `src/auth/`."**
Pick the files mode:
```
magpie review --files src/auth/login.ts src/auth/session.ts
```

**User: "Get a fast magpie sanity check on PR 4521 — I just want the output, don't post anything."**
```
magpie review 4521 -a --no-post --skip-context
```

**User: "Have magpie debate whether we should adopt tRPC."**
```
magpie discuss "Should we adopt tRPC for our internal APIs?"
```

## Configuration notes

- Magpie reads `~/.magpie/config.yaml` for providers, reviewers, analyzer, summarizer, and the context-gatherer config.
- CLI providers (`claude-code`, `codex-cli`, `gemini-cli`, `qwen-code`, `opencode-cli`) use the user's existing subscriptions/logins — no API keys needed and they're the recommended choice.
- If the user hasn't run `magpie init` yet, suggest `magpie init` (interactive) or `magpie init -y` (defaults) before the first review.
- If `magpie` is not on PATH, the project at `/home/tgrosinger/code/magpie` may need `npm install && npm run build && npm link` from its root.

## When *not* to use this skill

- The user is asking how magpie itself is implemented or wants to modify magpie's source — that's a normal code task in the magpie repo, not an invocation of this skill.
- The user wants a single-model review (just Claude reviewing the diff). Use the built-in `/code-review` skill instead.