GitHub - zulman/peer-review: A panel of AI agents that peer-reviews your document and hands back an improved version. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
zulman
peer-review
Public template
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>2 Commits<br>2 Commits
lib
lib
roles
roles
runs
runs
scripts
scripts
.gitignore
.gitignore
README.md
README.md
peer-review.sh
peer-review.sh
View all files
Repository files navigation
peer-review
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<br>reviewers argues over it from different angles, an editor resolves the<br>disagreements, and you get back a clean, well-thought-out document — plus a full<br>record of how the panel got there.
It works on anything : a design doc, a research note, a product plan, a policy<br>memo, a story, or a raw task that still needs a plan.
How it works
your text<br>[ editor: frame ] understand what the submission is and what to check<br>┌──────────────── one review round (repeats until settled) ───────────────┐<br>│ 5 reviewers run in parallel: │<br>│ optimist · pessimist · skeptic · googler · common-sense │<br>│ │ │<br>│ ▼ │<br>│ [ questioner ] are there still open questions? → CONTINUE / DONE │<br>│ │ (if open) targeted follow-up to the right reviewer │<br>│ ▼ │<br>│ [ editor: resolve ] turn the debate into concrete decisions │<br>└──────────────────────────────────────────────────────────────────────────┘<br>│ (when DONE, or round/safety cap reached)<br>[ editor: finalize ] write the improved document from the decisions<br>final.md + dialog.md + history.md
A storyteller narrates progress live in your terminal while this runs.
The panel
Reviewer<br>What it does
optimist<br>Finds positive scenarios and the real upside.
pessimist<br>Finds negative scenarios, risks, and failure modes.
skeptic<br>Distrusts any non-obvious claim made without proof.
googler<br>Searches the internet for similar cases and prior experience.
common-sense<br>Questions whether the effort is worth it; cuts busywork; keeps the shortest path to the goal.
Supporting agents: the editor (frame → resolve → finalize), the<br>questioner (validates whether anything is still unanswered), and the<br>storyteller (live narration).
Requirements
bash, plus standard Unix tools (awk, sed, grep).
The Cursor agent CLI on your PATH and a<br>CURSOR_API_KEY. (Or point --agent at any CLI that reads a prompt on stdin<br>and prints Markdown.)
Use --dry-run to try the pipeline with mock output and no API calls.
Using a different agent (Codex, opencode, …)
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<br>can switch without touching the code:
./peer-review.sh --agent "my-cli --some-flag" "..."<br># or: export PEER_REVIEW_AGENT="my-cli --some-flag"
If your CLI needs different flags (e.g. codex, opencode, Claude Code, etc.),<br>the integration point is the run_agent function in lib/common.sh. Don't want<br>to edit it by hand? Copy the prompt below and give it to your coding agent —<br>fill in the parts:
instead.
Please wire into the system:<br>- The only integration point is the `run_agent` function in `lib/common.sh` — the<br>block that builds the command when `PEER_REVIEW_AGENT` is `agent`. Add a branch<br>for (or make it the default).<br>- Each role is given its full instructions as one prompt string. must<br>receive that prompt, run fully non-interactively / headless, be allowed to read<br>the workspace at "$REPO_ROOT", and print ONLY the resulting Markdown to stdout<br>(no chat UI, no progress spinners, no streaming control characters).<br>- If "$PEER_REVIEW_MODEL" is set, pass it as the model.<br>- Keep everything else unchanged: the review loop, the roles, and the three output<br>files (final.md, dialog.md, history.md).<br>- Verify when done: `PEER_REVIEW_PROGRESS=0 ./peer-review.sh --dry-run "test"` still<br>yields exactly those three files, then do one real run...