A panel of AI agents that peer-reviews your document and hands back an improved version.
You give it a draft, a plan, a question, or a task. A team of specialized reviewers argues over it from different angles, an editor resolves the disagreements, and you get back a clean, well-thought-out document — plus a full record of how the panel got there.
It works on anything: a design doc, a research note, a product plan, a policy memo, a story, or a raw task that still needs a plan.
your text
│
▼
[ editor: frame ] understand what the submission is and what to check
│
▼
┌──────────────── one review round (repeats until settled) ───────────────┐
│ 5 reviewers run in parallel: │
│ optimist · pessimist · skeptic · googler · common-sense │
│ │ │
│ ▼ │
│ [ questioner ] are there still open questions? → CONTINUE / DONE │
│ │ (if open) targeted follow-up to the right reviewer │
│ ▼ │
│ [ editor: resolve ] turn the debate into concrete decisions │
└──────────────────────────────────────────────────────────────────────────┘
│ (when DONE, or round/safety cap reached)
▼
[ editor: finalize ] write the improved document from the decisions
│
▼
final.md + dialog.md + history.md
A storyteller narrates progress live in your terminal while this runs.
| Reviewer | What it does |
|---|---|
optimist |
Finds positive scenarios and the real upside. |
pessimist |
Finds negative scenarios, risks, and failure modes. |
skeptic |
Distrusts any non-obvious claim made without proof. |
googler |
Searches the internet for similar cases and prior experience. |
common-sense |
Questions whether the effort is worth it; cuts busywork; keeps the shortest path to the goal. |
Supporting agents: the editor (frame → resolve → finalize), the questioner (validates whether anything is still unanswered), and the storyteller (live narration).
bash, plus standard Unix tools (awk,sed,grep).- The Cursor
agentCLI on yourPATHand aCURSOR_API_KEY. (Or point--agentat any CLI that reads a prompt on stdin and prints Markdown.) - Use
--dry-runto try the pipeline with mock output and no API calls.
By default the system runs Cursor's agent command line for every role.
If your CLI just reads a prompt on stdin and prints Markdown to stdout, you can switch without touching the code:
./peer-review.sh --agent "my-cli --some-flag" "..."
# or: export PEER_REVIEW_AGENT="my-cli --some-flag"If your CLI needs different flags (e.g. codex, opencode, Claude Code, etc.),
the integration point is the run_agent function in lib/common.sh. Don't want
to edit it by hand? Copy the prompt below and give it to your coding agent —
fill in the <...> parts:
I use the `peer-review` tool in this folder. By default it runs Cursor's `agent`
CLI for every reviewer role. I want it to use <MY_CLI> instead.
Please wire <MY_CLI> into the system:
- The only integration point is the `run_agent` function in `lib/common.sh` — the
block that builds the command when `PEER_REVIEW_AGENT` is `agent`. Add a branch
for <MY_CLI> (or make it the default).
- Each role is given its full instructions as one prompt string. <MY_CLI> must
receive that prompt, run fully non-interactively / headless, be allowed to read
the workspace at "$REPO_ROOT", and print ONLY the resulting Markdown to stdout
(no chat UI, no progress spinners, no streaming control characters).
- If "$PEER_REVIEW_MODEL" is set, pass it as the model.
- Keep everything else unchanged: the review loop, the roles, and the three output
files (final.md, dialog.md, history.md).
- Verify when done: `PEER_REVIEW_PROGRESS=0 ./peer-review.sh --dry-run "test"` still
yields exactly those three files, then do one real run with <MY_CLI>.
My CLI details:
- Command to run one headless prompt: <e.g. `codex exec` / `opencode run`>
- How it takes the prompt (stdin / a `-p` flag / a file path): <fill in>
- Flag(s) to print only the final answer: <fill in, if any>
- Flag to set the model, if supported: <fill in, if any>
./peer-review.sh [options] "document, plan, question, or task"| Option | Meaning |
|---|---|
--workspace DIR |
Directory agents may read for evidence (default: current dir). |
--max-rounds N |
Cap on review rounds (default: unlimited). |
--model M |
Agent model for every role (e.g. sonnet-4). |
--agent CMD |
CLI used to run each role (default: agent). |
--dry-run |
Use mock outputs instead of spawning agents. |
-h, --help |
Show help. |
Environment overrides: PEER_REVIEW_MAX_ROUNDS, PEER_REVIEW_MODEL,
PEER_REVIEW_AGENT, PEER_REVIEW_AGENT_TIMEOUT, PEER_REVIEW_RUNS_DIR,
PEER_REVIEW_PROGRESS (set to 0 to silence the live status line),
CURSOR_API_KEY.
Each run creates a session folder under runs/ with exactly three files:
| File | What it is |
|---|---|
final.md |
The improved document — the deliverable. |
dialog.md |
The full log: every reviewer's analysis, the questions, the answers. |
history.md |
A short story of how the panel reached the result. |
Everything else produced during the run is cleaned up automatically.
# Review a design doc using the current directory as evidence
./peer-review.sh "Design doc for offline sync"
# Review against a specific repo, capped at 3 rounds
./peer-review.sh --workspace ~/my-repo --max-rounds 3 "Review this analytics memo"
# Try the pipeline without calling any agent
PEER_REVIEW_PROGRESS=0 ./peer-review.sh --dry-run "Interview script for architecture review"peer-review.sh entry point: parses args, runs the loop, prints results
lib/
common.sh config, session setup, prompt rendering, agent runner
orchestrator.sh the review loop: frame → rounds → finalize
finalize.sh finalize helpers + fallback document builder
revised_writer.sh writes final.md, builds dialog.md, cleans the session
storyteller.sh live narration + history.md
progress.sh the terminal status line
text.sh small text/role-label helpers
roles/ one Markdown prompt per agent role
runs/ session outputs (git-ignored)