Orchestrate structured multi-agent code review for local changes or GitHub PRs using the peanut-review CLI, and curate existing peanut-review sessions. Use when starting or managing review sessions, or when asked to deduplicate, shorten, validate, dismiss, filter, or decide whether agent review comments are worth pushing.
Orchestrate structured multi-agent code review for local changes or GitHub PRs using the peanut-review CLI, and curate existing peanut-review sessions. Use when starting or managing review sessions, or when asked to deduplicate, shorten, validate, dismiss, filter, or decide whether agent review comments are worth pushing.
Peanut Review
You are the orchestrator for a structured multi-agent review. Drive the review
lifecycle with tools/peanut-review/bin/peanut-review; it sets PYTHONPATH
for the local checkout, so no install step is needed.
Subcommands
Codex skills do not have a separate subcommand registry. Treat the first word
after /peanut-review as a routing hint when present:
/peanut-review curate <session-or-pr-context>: clean up an existing review
session's comments, using the dedicated curator agent when appropriate.
This is not a new reviewer pass.
/peanut-review pr <PR URL>: run the GitHub PR review lifecycle below.
/peanut-review local <base-ref>: run the author-owned local review
lifecycle below.
/peanut-review status <session-path>: inspect or recover a session without
changing comments unless asked.
For curate, start from the live session state and produce a push-ready,
author-facing comment set:
Resolve the live session path and source checkout. If the current directory
is a wrapper, read .peanut-review.json first and keep reviewRoot,
workspaceRoot, and repoRelative separate.
Inspect comments --format json before editing. Also inspect
comments --include-deleted --format json when duplicate cleanup, prior
deletions, or mistaken cleanup might matter.
Bucket local agent comments into keep/rewrite, merge, delete, or undelete.
Leave imported GitHub comments alone unless the discussion is actually
resolved or the user asks you to manage it.
Validate likely survivors against exact files, generated artifacts, or the
smallest useful repro/test. Spend verification time on comments that might
survive, not on likely deletes.
Rewrite kept comments as concise PR feedback. Start with the requested change
or scoped question, include only compact evidence, and align severity with
confidence. Avoid internal triage wording such as "confirmed" or "partly
confirmed".
Delete duplicate, incorrect, stale, nitpicky, speculative, praise-only,
overly broad, or low-ROI comments. When merging duplicates, edit the kept
comment first so it absorbs any useful detail, then delete the redundant
copy.
For GitHub-backed sessions, finish with gh-push --dry-run. Treat it as
authoritative for what will surface and whether anchors are pushable. If an
anchor is out of range, recreate the finding as a global comment preserving
the original file:line, then delete the stale anchored copy.
Do not launch or rerun reviewers, patch source, or push to GitHub during
curate unless the user explicitly asks. Launching the dedicated curator
agent is allowed when the user asks for curation or when a GitHub review
lifecycle reaches the automatic curation step.
Operator Checklist
Track these items explicitly. If your harness has a todo list, create this list
before running commands and keep it current.
Choose one lifecycle: GitHub PR review or local author-owned review.
Record the session path, source workspace, any separate build/tool root,
base/topic refs or PR number, and configured reviewers.
Ask for external facts/preferences that are not discoverable: review
root, web UI root, repo layout, build/test command, session reuse/archive
choice, persona lineup, runner, and model choices.
Confirm the checkout is built/testable and reviewer-visible tools are
reachable before launching reviewers.
Confirm project config and reviewer permissions are valid.
Launch reviewers and verify startup with status, logs, and
wait-all.
Inspect failed runs and non-review agent reports promptly.
Track the last reviewed comment id for later --since queries.
Triage every finding: keep, delete, resolve, reply, or push to GitHub.
Finish with the right artifact: GitHub review comments/verdict for PRs,
or a local verdict/archive for author-owned reviews.
Mode-specific checklist:
GitHub PR: prefer start --no-launch, build/test, then launch, unless
the user says the checkout is already built.
GitHub PR: after all reviewers signal round-done, let wait-all
launch and wait for the Curator agent by default; use --no-curate
only when you intentionally want to skip this.
GitHub PR: inspect the curated feedback; do not fix code, resolve
imported GitHub threads, or force rebuttal loops unless the user asks.
Local review: own the patch; apply fixes, migrate, run rebuttal passes,
and record a final verdict. Use the web UI's curator button or
curate only when comment cleanup is explicitly useful; use the web
UI's rerun-all button only when a fresh full reviewer pass is useful.
Ask Before Guessing
Use project config and discoverable local facts first. If a choice affects where
state is written, which checkout is reviewed, or which paid/local model runner
is used, and the answer is not already in the repo or user request, ask a
concise question instead of inventing it. Do not ask for facts you can cheaply
read from config files or CLI discovery.
If the lifecycle is unclear, ask: "Is this a local author-owned review, or a
GitHub PR review?"
Working Variables
Set these descriptive names in an operator scratchpad or shell snippets:
Examples assume PR_BIN and the intended SESSION path are set.
Name new sessions <repo>-<change-title>, using the PR head branch or local
branch/topic slug for change-title; avoid bare PR-number session names.
Config And Permissions
When .peanut-review.json exists, use it as-is. It belongs in the worktree
parent and defines reviewRoot, workspaceRoot, repoRelative,
reviewAgentTimeoutSeconds, and the exact agents lineup. Point the web UI at
the same reviewRoot. If no config exists, ask before choosing persistent
roots, repo layout, reviewers, runners, or models.
For GitHub PR sessions, the config must include a dedicated curator agent in
agents, for example {"name":"Curator","model":"gpt-5.5-high", "runner":"cursor","role":"curator"}. The curator uses a dedicated prompt, so
do not invent a curator.md persona. Do not rely on a Python default for the
curator model; missing curator config should fail before launch. Add the same
entry for local sessions when the web UI curator button or curate command
should be available.
Do not blur roots. reviewRoot is session storage/web UI state;
workspaceRoot + repoRelative identify the checkout under review. If build
outputs or project tools live outside the source checkout, make sure the actual
runner workspace and permissions let agents reach them before launch.
When root/layout changed or is ambiguous, dry-run before spending reviewer
runs:
The launch command validates config and Cursor permissions. Keep
Shell(peanut-review **) allowed, and keep Shell(**) out of the deny list
because it overrides all Shell allows.
When build tools live outside the runner workspace, Cursor permissions must
also allow the paths or commands reviewers are expected to use.
GitHub PR Review
Use this for PR numbers, PR URLs, or external author changes. Import GitHub
context, run reviewers, curate findings, then push review comments or an
approve/request-changes decision back to GitHub.
Start without launching unless the checkout is already built. The command
imports existing GitHub context and prints the session path.
Build/test the checkout with the project workflow. If reviewers need
non-obvious tool paths, make them available through the runner workspace
or rendered prompt before launch; do not use Agent reports as setup chat.
Launch reviewers and wait for the first pass plus automatic curation:
Inspect the curator's result. Delete duplicate/noisy local comments with
delete <c_id> if anything remains. Add replies only when they clarify a
finding for the PR author. Do not resolve imported GitHub comments unless
the GitHub discussion was actually resolved or the user asks you to manage
it.
Use --category comment or omit --category for non-verdict feedback. For
self-owned PRs, GitHub may reject approve/request-changes events; use a
normal global comment in that case.
After author updates, refresh the checkout with the project PR-update flow,
then run gh-pull and migrate. Rerun reviewers only for substantial updates
or a human request.
Triage every finding. Apply real fixes in code and resolve fixed comments;
reply with a concrete rebuttal for findings that are intentionally not fixed.
If the local comment set is too noisy, run the web UI's curator button or:
Use status for a compact view, but treat signal files, comments, reports, logs,
and live processes as the real health checks. process=... is supervisor-owned
runtime state; review=done means the agent posted round-done.
The authoritative reviewer prompt is
tools/peanut-review/peanut_review/templates/agent-prompt.md; do not maintain
a second skill-local copy. It tells agents to signal round-done and exit. The
supervisor should stop a lingering process shortly after observing that signal.
Use kill-agents only when status shows stale live processes, a launch needs
to be aborted, or the user explicitly asks.
There is no interactive agent help channel. If a reviewer is blocked, it may
record one Review Blocked report and exit without round-done; inspect the
runner log/report, fix the environment, then rerun it. Review discussion stays
in comments and anchored comment replies.
Reviewer Selection
Use configured reviewers as-is during a review. When authoring config, ask
before changing persistent roots, runners, personas, or models. If asked to
choose a lineup, include Vera, one domain expert suited to the patch, and two
or three breadth reviewers such as Felix, Petra, or Soren. Map tier: expert
personas to the strongest available model and
tier: standard to a balanced/fast model. Discover models with
cursor-agent --list-models or opencode models; common Codex ids are
gpt-5.5-high, gpt-5.5, gpt-5.4, and gpt-5.3-codex.
Use display-case agent names in config, e.g. Vera, while keeping persona
filenames lowercase, e.g. vera.md. The web UI shows the configured agent
name.
Web UI
The web UI reads the same session storage as the CLI. Its --root should match
the configured reviewRoot; without --root, it uses $PEANUT_SESSION's
parent if set, otherwise /tmp/peanut-review.
If the user says the review server is already up, discover its root from the
running peanut_review serve --root ... process and use that for session
storage instead of starting a new server or guessing a different root.
cursor: cursor-agent --print through Shell/CLI, not MCP; isolated
runtime home under <session>/runtime/cursor/.
opencode: opencode run; model ids are provider/model, including
openai/*, opencode/*, or local llama.cpp/*.
codex: codex exec; requires codex login and gets
--add-dir <session> so it can write session files. Set per-agent
"fastMode": true to enable Codex fast mode. It defaults to false.
Agents submit findings, comment replies, non-review reports, and completion
signals with peanut-review CLI commands from the rendered prompt. The note
channel is only for reports such as test execution and comment curation; notes
are not pushed to GitHub.
Failure Handling
If an agent times out, inspect status and <session>/log/.
If an agent exits without round-done, treat it as failed or incomplete and
use rerun --agent <name> after confirming no live reviewer remains.
If a session was launched under bad assumptions, prefer archiving it and
starting fresh over reusing stale signals/comments.
If the orchestrator crashes, run status, then resume from the latest
comments, reports, logs, and signal state.
