pi-review

Isolated, multi-reviewer AI code review — as a CLI, a CI gate, and an agent skill.

Quick start · Features · Screening workflow · Panel review · CLI reference · 中文说明

---

pi-review hands review work to a fresh, read-only Pi session and returns a structured verdict: findings with severity, evidence, location and a stable exit code. Run one reviewer, or a panel of independent reviewers that must agree before a finding blocks the gate. Your agent (Claude Code, Codex, Cursor, Pi) stays the only editor.

npm install -g @zephyrdeng/pi-review
pi-review -- @src/foo.ts                                      # one reviewer
pi-review --panel code-experts --consensus majority -- @src   # three lenses, one gate

Why pi-review

Isolated, read-only reviewers	Every review is a fresh child process with a hard read,grep,find,ls allowlist. It cannot edit, commit, or leak context from your main session.
Panel consensus, not one opinion	2–8 independent reviewers who never see each other. A finding blocks only when enough of them agree (any / quorum / majority / unanimous); singletons stay visible as advisories.
Mix models per reviewer	--reviewer-model r1=openai/gpt-5.6:high --reviewer-model r2=anthropic/claude-opus-4.8:xhigh — cross-family panels catch what one vendor misses.
Machine-readable, host-agnostic	One versioned PI_REVIEW_META_JSON line, exit codes 0/1/3/4, and an events-jsonl stream. Drop into CI, hooks, or your own renderer.
Loop gate for agent closeout	pi-review loop --until clean re-reviews after each fix round, diffs findings across rounds, and stops on convergence — never unbounded.
~1s screening	pi-review screen skips LLM generation entirely: deterministic slicing + typed Jev judgments against a defect catalog. Measured 1.2s vs 30–50s for a full round. The catalog grows from use — custom patterns + a signal log via pi-review screen-memory.
Live everywhere	Native live rows in Pi, a loopback web dashboard for Claude Code / Codex, streamed milestones on stderr for plain terminals.
Three review modes	code (correctness, security, tests), plan (six expert lenses), challenge (adversarial pressure test). Extend via JSON presets.

See it work

Every review ends with a structured report and a footer you can read at a glance:

── pi-review ────────────────────────────
  Verdict     ! REQUEST CHANGES
  Status      HAS FINDINGS
  Mode        code
  Findings    1 actionable / 1 total
  Model       provider/model
  Tokens      in 17.6K · out 512 · cache 2.0K · total 18.2K
  Cost        $0.05
  Duration    42.3s
──────────────────────────────────────────

Scripts read PI_REVIEW_META_JSON: from stderr — findings carry severity, path, location, details, recommendation. No Markdown scraping. → Output & integration

Quick start

Prerequisite: Pi CLI with at least one model provider configured.

# CLI
npm install -g @zephyrdeng/pi-review

# …or one shot: Pi package + skill for Claude Code / Codex / Cursor / Antigravity
npx @zephyrdeng/pi-review install

pi-review -- @src/foo.ts                                   # single review
pi-review --mode plan -- @docs/architecture.md             # multi-lens plan review
pi-review --reviewers 3 --consensus quorum -- @src         # panel
pi-review loop --until clean --max-rounds 5 -- @src        # bounded fix/re-review gate
pi-review screen src/order-service.ts                      # ~1s catalog screening
pi-review models                                           # what can I run on?

In Pi: /rv @src, /rv-loop fix until clean @src, /rv-models. In other agent hosts, install the skill once and ask for a review in plain language.

→ Installation options · Pi /rv commands

How the panel decides

reviewers (isolated, read-only) ──► findings ──► deterministic match (path + summary)
                                                      │
                                       ambiguous pairs ┴─► Jev typed adjudication (~100 ms)
                                                             │  borderline 0.3–0.7 → one Pi re-judge
                                                             ▼
                                           consensus threshold ──► confirmed (blocks) / advisory

Reviewer failure → blocked; unparseable output → needs_human; never a silent pass. Adjudication cannot invent, drop, or rewrite findings — it only clusters. → Panel review in depth · Loop review

Partners

OrcaRouter

One key, every frontier model. pi-review ships a ready-made provider file — drop it into Pi and run cross-family panels without juggling vendor accounts.

→ Setup guide

TypeSafe Jev

A System One model that answers typed questions with probabilities in ~100 ms. Powers consensus adjudication, cross-round finding memory, scope classify, and the 1-second screen gate.

Set TYPESAFE_API_KEY and it switches on.

→ Comparison report · Screening study

Project rules

Reviewer children also read .claude/rules/, with Claude Code semantics: user-level ~/.claude/rules/ plus project-level <dir>/.claude/rules/ discovered from the child's working directory upward. Rules without a paths frontmatter key are appended to the child's system prompt; rules with paths are injected into the read result only when the read file matches the glob. write and edit never trigger them.

Review children still run isolated (--no-extensions, issue #8); the rules loader is our own extension, loaded explicitly with --extension. Turn it off for one run with --no-rules or PI_REVIEW_RULES=0 (also accepts false / off / no). The consensus adjudicator, screen, and classify never load rules — the adjudicator only clusters findings.

Documentation

Guide	What's inside
Installation	CLI, Pi package, agent skills (Claude Code / Codex / Cursor / agy), updates, from source
CLI reference	Every flag, review modes, when to use which command
Fast screening	The screen workflow, gate outcomes, machine output, and CI placement
Panel review	Consensus policies, aggregation, Jev, classify, screen, live UI, web dashboard
Loop review	Bounded rounds, --until clean, cross-round comparison, convergence stop
Output & integration	Markdown shape, PI_REVIEW_META_JSON schema, exit codes, sessions, progress logs
Configuration	Config file, environment variables, security model
Providers	OrcaRouter and other provider setup
Research	Jev architecture, screening measurements, adjudication case studies

Contributing

Issues and PRs welcome. Source is English-only; docs may be bilingual. Commits go through ai-commit via Husky (npm install sets up the hooks). See installation → contributing.

Star history

If pi-review caught a bug before your reviewer did, a ⭐ helps others find it.

Acknowledgments

System prompt structure inspired by Codex-5.5-codex-instruct-5.5 (MIT).

License

MIT © ZephyrDeng