pi-review

Pi extension for code review that runs in the foreground: /review hands a directive to the main agent, which runs one subagent({ workflowScript, async:false }) call that fans out parallel reviewers and an inline gate. The whole review streams in chat — no silent background work.

Requires the pi-subagents extension (pi install npm:pi-subagents, ≥0.41) — it provides the subagent tool's workflowScript surface used to fan out.

Pattern ported from the Claude code-review plugin. See reference/ for upstream flow notes and the version roadmap.

Commands

/review [any prompt] [--lite] [--gate-model <id>]
/review-config
/review-agents
/review-show

/review

CC-aligned: text after /review is user context. The extension prepares the run deterministically (v0.7): it resolves the target, acquires the diff, records a manifest (.pi/pi-review/runs/<runId>/manifest.json), and — for PRs — checks out the target repo into a scratch workspace. The main agent then runs one subagent({ workflowScript, async:false }) and calls pi_review_report to finalize the report.

When called with no arguments, /review targets local git:

1. If the working tree is dirty → git diff HEAD into .pi/pi-review/runs/<runId>/change.diff.
2. If clean → git fetch origin <default-branch>, then git diff origin/<default-branch>...HEAD (avoids a stale local main/master).
3. Writes manifest.json (base/head SHAs, diff SHA-256, changed files, docs-only flag, rule paths, history availability).
4. Outside a git repo with no PR → notify and exit.

PR review: pass a GitHub PR URL or number. The extension tries gh pr view + gh pr diff; if the diff is too large (GitHub 20k-line limit) or unavailable, it fetches pull/<n>/head + the PR base ref and runs a three-dot git diff. Oversized PRs no longer fail in the plugin layer. Reviewers run from a target workspace (a shallow clone with the PR head checked out), so history-context / code-comments correctly see the reviewed repo even when the plugin runs from a different directory.

/review https://github.com/org/repo/pull/17206
/review 17206
/review focus on backup restore — PR 17206

Lite mode: add --lite for a fast single-agent pass — one reviewer covers all dimensions (bugs / security / compliance / code-comments / history), no fan-out, no gate. Lower latency and cost; ideal for a quick gut-check.

/review --lite
/review --lite focus on concurrency and secret handling

Flags

The surface is intentionally minimal. Removed knobs (--threshold / --reviewer / --no-gate / --score-per-issue / --diff) are accepted-but-ignored so old invocations do not break; their capabilities now live in config.json via /review-config.

Flag	Effect
--lite	Single-agent fast mode: one reviewer, no gate.
--gate-model <id>	Override the gate model for this run (otherwise config.gate.model).
--no-spawn	Dry run — print the prepared run summary (mode, diff SHA, workspace, roster); side-effect free (no pruning).

Removed flags → config

Old flag	config.json key
--threshold N	gate.threshold
--reviewer id	reviewers.<id>.enabled
--no-gate	gate.enabled
--score-per-issue MODE	gate.scorePerIssue
--diff path	(removed — pass a PR url or run in a dirty repo instead)

Bundled reviewers (v0.5.1 lean agents)

Runtime names are pi-review.<id> (package agents registered via pi.subagents.agents).

ID	Purpose	Default	Tools
claude-md-compliance	Project rules (AGENTS.md / CLAUDE.md / .pi/)	enabled	read, grep, ls
bugbot	Obvious bugs in introduced lines only	enabled	read, grep, bash
history-context	Light git blame / log (≤5 files, log -n 5)	enabled	read, bash
security-review	Security issues introduced by the change	enabled	read, grep, bash
code-comments	Inline comment / TODO guidance in changed files	enabled	read, grep
conventions	De-facto style pass	disabled	read, grep, ls
gate	Dedupe + re-score + verdict	(always)	read
lite-review	Single-agent all-dimensions (--lite)	on demand	read, grep, bash

Pipeline

/review runs in the foreground. The extension prepares the run, then:

Step 0  extension: resolve target → acquire diff + manifest → prepare target workspace
Step 1  main agent verifies the prepared manifest/workspace (one bash call)
Step 2  subagent({ workflowScript, async:false }) — once
          runs.all([ pi-review.* reviewers … ]) → runs.run("gate", { structuredOutput })
Step 3  pi_review_report tool → code-side verdict + persisted session entry + markdown

Every reviewer and the gate carry outputSchema; the workflow consumes result.structuredOutput (never free-text). Reviewer findings include status (ok/limited/skipped) and coverage; the gate emits per-candidate dispositions (kept / dropped / merged) so high-severity candidates are never silently lost.

Permissions: the extension performs diff/clone/fetch via its own subprocesses. It no longer writes .pi/projects/<id>/permissions.local.json. Reviewer children rely on their tools: allowlist (read/grep and a few read-only git commands) — no persistent project permission mutation.

Cost: dominated by N × tool turns. Prefer --lite for a cheap pass. Reviewer thinking inherits the parent session; only the gate uses config.gate.thinking.

Configuration

Per-user config lives at:

~/.pi/agent/pi-review.json

Run /review-config to open it in $EDITOR. The file is loaded, merged with the built-in defaults, and validated on every /review call. Unknown reviewer ids are added as new reviewers; known ids are patched in place.

{
  "schemaVersion": 1,
  "gate": {
    // Cheap tier by default (pure de-noise reasoning). "inherit" follows the parent session.
    // Override to a specific id; non-anthropic providers must set this explicitly.
    "model": "anthropic/claude-haiku-4-5",
    "thinking": "low",
    "enabled": true,
    // Issues with confidence < threshold are dropped (code-enforced).
    "threshold": 8,
    // Verdict policy: "strict" (any surviving blocker/major → request_changes)
    // | "legacy" (≥3 majors). Code-side enforced.
    "verdictPolicy": "strict"
  },
  "routing": {
    // "adaptive" (default) drops clearly-inapplicable lanes (no rule files,
    // docs-only, no git history) before spawning. "all" keeps the full roster.
    "mode": "adaptive"
  },
  "budgets": {
    "turnBudget": { "maxTurns": 20, "graceTurns": 2 }
  },
  "reviewers": {
    "claude-md-compliance": {
      "model": "anthropic/claude-opus-4-6",
      "thinking": "high",
      "enabled": true
    },
    "bugbot": {
      "model": "inherit",
      "thinking": "medium"
    }
  }
}

Use "model": "inherit" on a reviewer to follow the parent session's model; per-reviewer thinking is passed through to the child subagent. The gate defaults to a cheap tier; override it persistently via gate.model, or per-run with --gate-model <id>.

Legacy keys (concurrency, inheritance, gate.scorePerIssue, reviewers.<id>.tools, reviewers.<id>.timeoutMs) are ignored — /review prints one migration warning when present. Remove them from your config to silence the warning.

TUI output

The pi_review_report tool renders deterministic markdown into chat and persists a machine-readable session entry. A collapsible TUI renderer shows a verdict + count preview line; /review-show re-renders the most recent report. Shape (illustrative):

## pi-review — uncommitted changes

**Verdict: REQUEST_CHANGES** (1 blockers · 1 major · 0 minor · 0 nit)
Reviewed in 42.1s · 4 reviewers · 1 gate

### claude-md-compliance (anthropic/claude-opus-4-6) — ok · 12.0s
- 1 issue
- [BLOCKER · compliance · conf 9] `src/auth.ts:42` — rule "no raw token logging" violated

### bug-detector (anthropic/claude-sonnet-4-6) — ok · 8.1s
- 1 issue
- [MAJOR · bug · conf 8] `src/auth.ts:42` — race: missing await on fetchUser

### conventions (anthropic/claude-sonnet-4-6) — ok · 6.2s
- 0 issues
- all naming/imports match surrounding files

### history-context (anthropic/claude-haiku-4-5) — ok · 4.8s
- 0 issues
- touched files have stable history, no recent reverts

### gate (anthropic/claude-haiku-4-5) — ok · 5.4s
- verdict: request_changes
- reason: One auth.ts blocker + one race condition in worker.ts; safe to merge after fixes.
- 2 issues after dedupe + threshold

A machine-readable copy is also written via pi.appendEntry("pi-review", { ... }) for future TUI consumers.

Install

pi install npm:@georgedong32/pi-review

Verify:

pi list

Local development

bun install
bun run check     # tsc --noEmit
bun test          # node:test + tsx

Repo structure

index.ts                  Pi extension entry; registers /review + /review-config + /review-agents + /review-show
src/review-run.ts         Plugin-side run prep: diff acquisition, manifest, directive (active path)
src/target-workspace.ts   PR target checkout (workspace for reviewers)
src/review-report.ts      Manifest + diff helpers (SHA-256, changed-files, rule paths, prune)
src/directive.ts          Directive + workflowScript generator (outputSchema, single-wave)
src/workflow-schemas.ts   JSON Schema for reviewer / gate structured output
src/report-tool.ts        pi_review_report implementation (code-side enforce + render)
src/tool-wrapper.ts       Register the report tool
src/tui-renderer.ts       Collapsible TUI renderer for "pi-review" cards
src/report.ts             buildReportFromWorkflow + renderReport
src/gate-enforce.ts       Dedupe + threshold + strict/legacy verdict (deterministic)
src/types.ts              Shared interfaces
src/config.ts             loadConfig / mergeWithDefaults / validateConfig / writeConfig
src/workflow-schemas.ts  outputSchema fragments for reviewer + gate children
agents/*.md               Bundled reviewer prompts (gate.md is the gate prompt)
tests/*.test.ts           node:test suites

Limitations (v1)

• No automatic retry: a failed reviewer is recorded as ok=false and the rest of the run continues. The gate still runs.
• The prepared target workspace (for PRs) is a shallow clone (depth 50) under the OS tmpdir (pi-review-ws-*), pruned by a 24h TTL; run manifests + diffs live under .pi/pi-review/runs/ (same TTL). It is not a full worktree with build state.
• GitHub: the extension uses gh/git to obtain PRs; oversized diffs fall back to git. PR comments are not posted.
• No web config UI: only $EDITOR.

License

Apache-2.0