dotfiles/home/.agents/skills/magpie-review/SKILL.md

name, description

name

description

magpie-review

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.