pi-pr-review

Parallel, model-agnostic AI code review for GitHub pull requests in the Pi coding agent.

Give it a PR number and it will:

• fetch the PR metadata and diff with gh;
• run focused review passes in parallel using models you choose;
• validate candidate findings before reporting them;
• render a structured review with severity, location, confidence, and verdict;
• optionally publish one safe GitHub review with inline comments (fully parsed, complete Markdown and strict host-bound JSON share the same gated APPROVE path; degraded reviews remain COMMENT).

The default review prioritizes P0–P2 defects and allows up to three minor findings. Use --full for exhaustive convention, maintainability, and minor coverage.

Requirements

• Pi 0.80.5 or newer (the first release with the terminal agent_settled lifecycle event).
• gh installed and authenticated with gh auth login.
• Pi running inside the repository that owns the PR.

Install

# User scope
pi install npm:pi-pr-review

# Project scope
pi install -l npm:pi-pr-review

For local development, replace the package name with a checkout path such as ./pi-pr-review.

Quick start

Configure the reviewer models:

/pr-review-config light=<fast-model> medium=<balanced-model> heavy=<strong-model>
/pr-review-config light_thinking=low medium_thinking=medium heavy_thinking=high

Then review a PR in the current repository:

/pr-review 123

The semantic result is predictable human-readable Markdown in every mode. GitHub request JSON is generated only by host code and is never a model output contract.

Review modes

Command	Behavior
/pr-review 123	Balanced default: all validated P0–P2 findings plus up to three direct-diff P3/nits.
/pr-review 123 --major-only	P0–P2 only.
/pr-review 123 --full	Adds convention/maintainability review and reports all qualifying severities.
/pr-review 123 --balanced	Explicit alias for the default mode.
/pr-review 123 --include-closed	Reviews a closed or merged PR without asking first.

--full, --major-only, and --balanced are mutually exclusive. Without --include-closed or --review-closed, Pi asks before reviewing a non-open PR.

A review uses five focused passes by default:

1. overview and minor hygiene (light);
2. state, lifecycle, and concurrency correctness (heavy);
3. contracts, data, and integration correctness (heavy);
4. security (heavy);
5. performance and resource ownership (heavy).

--full adds a convention and maintainability pass (medium). Large multi-file diffs are split by whole-file boundaries and reviewed in parallel. If the extension is unavailable, the prompt falls back to the current Pi session model.

Focus running reviewers

While a review is running in the interactive TUI, open the live read-only subagent view with:

/pr-review-focus

Ctrl+Alt+R opens the same view without entering a command. The viewer keeps the parent review running and does not switch Pi sessions or attach an interactive terminal to a child process.

Viewer controls:

Key	Action
Tab / Right	Focus the next pass.
Shift+Tab / Left	Focus the previous pass.
Up / Down	Scroll one line.
PageUp / PageDown	Scroll one page.
Home / End	Jump to the start or resume following live output.
Esc	Return to the main thread without cancelling the review.

The view shows pass status, attempt/model, tool names and completion state, and bounded assistant output. It never stores the pass objective, input context, captured diff, raw child events, tool arguments, tool results, or stderr. Assistant text is sanitized and capped at 48 KiB per pass and 256 KiB across the active review; older text is evicted with an on-screen marker.

The bounded viewer is a projection, not the authoritative lane result. Separately, the host retains an invocation-scoped artifact for each lane with its exact final assistant text, lifecycle (complete, partial, timed_out, or failed), requested/observed model, process outcome, attempt/fallback history, scheduling offsets, timing, and tool-use counts. Both stores exist only in memory for the active session/cwd-bound /pr-review generation and are synchronously purged on completion, cancellation, replacement, or session/tree lifecycle changes.

The viewer intentionally cannot send prompts, steering, or follow-ups to reviewers. It is unavailable in print, JSON, and RPC modes and outside an active user-initiated /pr-review loop.

Configure models

/pr-review-config opens an interactive settings menu in the TUI. Use /pr-review-config show for a text summary or key=value arguments for direct changes.

Tier	Purpose
light	Fast overview and risk scan.
medium	Convention and maintainability review in --full mode.
heavy	Correctness, security, and performance review.

Common settings:

/pr-review-config light=provider/model heavy=provider/model:high
/pr-review-config heavy_fallbacks=provider/backup:high,provider/backup2
/pr-review-config light_thinking=low medium_thinking=medium heavy_thinking=high
/pr-review-config heavy_tool_policy=configured
/pr-review-config tools=read,bash,grep,find,ls
/pr-review-config auto_post_reviews=true
/pr-review-config allow_stale_publish=false
/pr-review-config allow_stale_approvals=true
/pr-review-config approve_max_priority_level=P2
/pr-review-config medium=unset

Supported thinking levels are off, minimal, low, medium, high, xhigh, and max. A thinking suffix in a model spec, such as provider/model:xhigh, takes precedence over the tier's thinking setting. unset restores inherited behavior.

Tool policy can be none or configured. configured uses the tools allowlist; because an allowlist containing bash is not technically read-only, remove it if you need stricter reviewer isolation. Reviewer subprocesses disable extension discovery, strip the package's review-tool names from this allowlist, and use --no-tools when no allowed tools remain.

Configuration is stored in:

• user scope: ~/.pi/agent/pr-review.json;
• project scope: <repo>/.pi/pr-review.json, applied only when the project is trusted.

A trusted project can override model, tool, and publication settings. Verification profiles are always user-only.

Example:

{
  "tiers": {
    "light": "provider/fast-model",
    "medium": "provider/balanced-model",
    "heavy": "provider/strong-model:high"
  },
  "fallbacks": {
    "heavy": ["provider/backup-model:high"]
  },
  "thinkingLevels": {
    "light": "low",
    "medium": "medium",
    "heavy": "high"
  },
  "toolPolicies": {
    "light": "none",
    "medium": "configured",
    "heavy": "configured"
  },
  "tools": ["read", "bash", "grep", "find", "ls"],
  "deadlines": {
    "attemptMs": { "light": 180000, "medium": 360000, "heavy": 480000 },
    "fallbackAttemptMs": 180000,
    "batchMs": 720000,
    "synthesisMs": 60000,
    "totalMs": 900000,
    "terminationGraceMs": 5000,
    "cleanupReserveMs": 5000,
    "minimumFallbackMs": 30000
  },
  "autoPostReviews": false,
  "allowStalePublish": true,
  "allowStaleApprovals": false,
  "approveMaxPriorityLevel": "off"
}

Every invocation has a host-owned monotonic 15-minute hard cap, including the two GitHub identity/lifecycle preflights, synthesis, termination grace, and reserved cleanup. The dependent preflight calls share the one invocation budget, so they cannot each add an independent command timeout before review timing begins. Defaults bound light/medium/heavy attempts to 3/6/8 minutes, a fallback attempt to 3 minutes, and the concurrent batch to 12 minutes. The complete deadlines object may be replaced at user scope or by a trusted project; partial, malformed, non-integer, out-of-range, or internally inconsistent objects are rejected as a unit and the last valid/default finite budget remains active. Supported inclusive ranges are: attempts 30–720 seconds, fallback 30–360 seconds, batch 60–840 seconds, synthesis 10–120 seconds, total 120–1200 seconds, TERM grace 0.1–15 seconds, cleanup reserve 1–30 seconds, and minimum useful fallback 10–120 seconds. Minimum fallback must not exceed its attempt cap, and batch + synthesis + termination grace + cleanup must fit inside total.

A timed-out or retryable quota/rate-limit/capacity lane may start at most one configured fallback attempt. It starts only when at least minimumFallbackMs plus cleanup reserve remains; the host never changes the configured model, thinking level, or tool policy to save time. If a tier is unset, its existing nearest-configured-tier/Pi-default behavior is unchanged.

On an attempt deadline the host records timeout separately from user cancellation, sends TERM to the original child, waits only terminationGraceMs, then sends KILL if no exit was observed and stops draining after the cleanup reserve. Partial assistant text and telemetry survive this lifecycle. The synthesis cap arms only once review work goes quiet: any turn that starts or any review tool that runs again while the cap is armed defers it, and it re-arms from the next turn end, so early review-tool turns (for example verification discovery) cannot starve later heavy lanes. Batch/total expiry stops queued work and waiting lanes; completed and partial artifacts proceed to Markdown synthesis or deterministic lane assembly, identify every incomplete lens/shard, and remain eligible for the safe body-only COMMENT publication path. A timed-out lane is never reported as NO FINDINGS or full coverage, and a lane ended by the host total or synthesis deadline is disclosed with that kind (deadline_expired) instead of being mistaken for its own attempt deadline expiring. Host lane artifacts are authoritative for completeness in both directions: a false assistant completion claim cannot upgrade incomplete lanes, and a paraphrased or omitted Lane completeness line cannot downgrade a host-complete batch away from the concise renderer.

Initial operating targets are ordinary-review p50 ≤ 6 minutes and p95 ≤ 12 minutes, and large-review p50 ≤ 10 minutes and p95 ≤ 14 minutes, with the 15-minute hard cap authoritative. Invocation telemetry starts before GitHub preflight and records configured deadline source/caps, termination grace, cleanup reserve, and active wall time; batch details record first event/output timing, lifecycle counts, configured and effective batch-truncated attempt deadlines, fallback starts/budget rejections, external total/synthesis deadline expiries per lane, and termination grace/escalation data. These are initial production targets, not a promise that every provider completes before its host deadline.

Ordinary reviewer output is reconstructed from every text part of the authoritative final assistant message in order. A zero process exit is not enough to mark a lane complete: completion also requires a terminal stop and the expected lane sections (or an explicitly emitted NO FINDINGS. where that response is allowed). Empty success is never synthesized into NO FINDINGS.; length-limited, malformed, timed-out, and failed attempts retain their raw text with an explicit lifecycle. Batch details include raw text, attempt artifacts, lifecycle counts and elapsed totals, while the displayed batch remains in deterministic input order.

One-shot self-review for top-level tasks

For an eligible long-running coding task started by direct interactive or RPC input, Pi exposes self_review_subagent near the end of the task. The tool takes no arguments. Its empty schema is closed with additionalProperties: false; the extension—not the caller—fixes the objective, heavy tier, P0–P2-only severity policy, no-minor-hygiene policy, and no-tools isolation.

The permit is bound to one top-level task generation, the Pi session instance, cwd, and canonical Git worktree. Dispatch is additionally bound to the tool-call ID from an assistant message_end containing exactly one tool call, self_review_subagent; mixed, multiple, or direct unbound dispatches are denied without consuming the reusable task permit. A bound permit is consumed atomically before delta capture, so concurrent or replayed calls are rejected and the tool is hidden immediately. It is never available during /pr-review. Low-level agent_end events do not revoke it because Pi may still retry, compact, or run queued continuations; unused authority is cleared only at terminal agent_settled (or earlier cancellation/session/input boundaries).

The child uses Pi RPC mode with a bounded ten-minute total runtime. Before startup, the host creates a mode-0700 temporary PI_CODING_AGENT_DIR, copies and normalizes the trusted user settings there with retry and compaction disabled, and exposes only validated regular auth.json/models.json files through controlled symlinks. The same private directory—not the mutable worktree—is the child process cwd, and inherited runtime preload flags (NODE_OPTIONS and BUN_OPTIONS) are removed. RPC control acknowledgements can therefore persist only to temporary settings. The host attempts synchronous recursive removal after every supervised outcome; unsafe source configuration or cleanup failure fails the call closed. Environment-based authentication otherwise remains inherited, and no credentials are placed in arguments or prompts. The host waits for acknowledgements that automatic compaction and automatic retry are disabled before it submits the sole prompt, and it also aborts on timeout, bounded stdout/stderr overflow, any retry/compaction lifecycle event, or a second agent_start. There is no fallback, sharding, extension discovery, tools, publication, or verification behavior.

Self-review is deliberately fail-closed. At extension startup, the host resolves one canonical executable Git from that startup PATH; the same absolute executable is bound through clean-baseline capture, permit validation, and delta capture, so later PATH changes cannot select repository-controlled Git. The worktree must be clean when the top-level task starts and HEAD must remain unchanged. Baseline capture receives its abort signal immediately, so new input, cancellation, or session/tree navigation can stop even the initial Git inspection. At execution, the host builds a complete bounded diff of Git-visible tracked, staged, and non-ignored untracked changes relative to that starting HEAD. It rejects an empty delta, any changed or dirty submodule, more than 200 status records, more than 4 MiB of diff, a changed session/cwd/worktree/HEAD, or a status change during capture.

The child must return strict JSON containing only a findings array. Every finding must pass an exact host-owned schema: P0/P1/P2 severity and matching title/blocking state, concrete impact/trigger/evidence strings, normalized repo-relative changed-line coordinates, side, task/diff relationship flags, and bounded confidence. The host derives changed-line anchors from the captured unified diff and requires each claimed range to lie completely within one changed-line run in one hunk on the exact claimed path and side; binary and no-hunk paths have no valid anchors. Markdown, malformed JSON, extra or missing fields, P3/nits, inconsistent metadata, out-of-delta anchors, and unsafe paths are rejected rather than shown as review results. No findings is {"findings":[]}.

This is a practical Git-derived boundary, not a filesystem snapshot or sandbox. Ignored files are not included, and an external process that rewrites ordinary file contents without changing status shape could race capture. Requiring a clean start, rejecting submodule deltas, checking HEAD and status before/after capture, incrementally bounding all output, and failing closed avoids silently presenting a partial oversized delta. The RPC leader starts in a detached POSIX process group; on failure, abort, timeout, or retained descendants, the host sends group TERM then KILL, destroys inherited pipes, and stops waiting after a bounded drain deadline. A descendant that deliberately creates a different process group/session can escape those signals, although it cannot force the host to retain the supervised pipes indefinitely. Use a separate sandbox or snapshot system when stronger filesystem, process, or network isolation is required.

Publish to GitHub

Publishing is off by default.

/pr-review 123 --comment       # publish this run
/pr-review 123 --no-comment    # never publish this run
/pr-review-config auto_post_reviews=true

The extension owns normal publishing. Before review execution it captures repository, hostname, PR number/title, reviewed head, lifecycle state, posting/stale authority, and invocation identity independently of assistant text. After synthesis, it caches one validated completed review (the host-owned canonical artifact) per repository and PR in the current Pi session. autoPostReviews and --comment publish that cached review after completion; --no-comment suppresses publication for the run.

Review semantics are Markdown-first. A deterministic tolerant parser normalizes line endings, extracts complete findings when possible, and ignores heading-like text inside CommonMark fenced-code and HTML-block contexts. Every degraded synthesis — ambiguous, partially parsed, incomplete lane coverage, or absent terminal synthesis — publishes one deterministic host-rendered COMMENT body with generic code-review labels: a Coverage section with the exact lane lifecycle disclosure, a Findings section with host-formatted parsed findings (never a clean-review claim when nothing parsed), and the complete original synthesis plus every retained lane artifact preserved verbatim under Retained synthesis / Retained lane output with heading levels shifted so they nest. A contradictory completion claim inside retained text is reconciled to the host verdict. Reserved markers are sanitized, size limits are enforced, and the canonical marker is appended only by host code. Optional formatting repair is never required and can never suppress the degraded fallback.

You can publish the cache later with /pr-review-publish 123, or directly ask the agent to “post the inline review,” “post it as an inline review,” or “publish the review for PR #123.” The extension handles that request directly before an agent turn. /pr-review-publish and a matching direct request publish only the cache; they never start or rerun review agents. Unnumbered direct requests select the latest cached review for the current repository. Only fresh interactive/RPC input can use the direct path.

Every authorized publish path builds one GitHub review payload and sends at most one review POST; it never submits REQUEST_CHANGES or retries a rejected write with a fallback POST. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch may emit a gated APPROVE through the same host binding, priority, lifecycle, self-author, and stale checks as strict JSON. Host lane evidence is authoritative for completeness: a paraphrased or omitted All requested lanes completed. disclosure cannot downgrade a host-complete batch, and a false disclosure cannot upgrade incomplete or missing lane coverage; the assistant's canonical line is consulted only when no batch evidence exists. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside Findings, incomplete or missing host lane coverage, malformed or unsafe output, and lane-fallback artifacts remain COMMENT reviews; their safely parsed findings keep inline placement, while unparsable output publishes body-only. Cache restore reclassifies persisted lane output and requires the exact host-recorded artifact key set, with every complete artifact matching the frozen invocation generation, tier, and minor-hygiene contract, and re-synthesizes the retained raw text under that frozen binding before retaining approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The concise top-level body starts with the verdict, points readers to inline findings, and places nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow under Other Notes; overview, verification, strengths, and transport diagnostics stay out of the public summary. The complete original Markdown remains retained internally; if the concise body plus its canonical marker exceeds GitHub's limit, the host uses its sanitized, size-bounded Markdown projection instead of dropping the review. Stale or authorized non-open reviews are body-only. A stale approval additionally requires allowStaleApprovals: true.

All publication paths apply host-enforced safety gates: captured posting authority, repository and requested-PR binding, reviewed/current-head and stale policy, bounded bodies and payloads, draft and lifecycle checks, non-open authorization, authenticated-identity same-head duplicate detection, and a final head check. Fully or partially parsed review paths additionally enforce safe inline locations, including degraded incomplete-lane reviews whose findings still parse. Raw and lane-assembled fallbacks without parsed findings are body-only; every degraded path is COMMENT-only, and assistant text cannot select event, commit, repository, hostname, API path, or inline anchors. Unknown or invalid host states fail closed before a write.

Stale publication is enabled by default through allowStalePublish: true; disable it with /pr-review-config allow_stale_publish=false. Automatic posting and /pr-review-publish use the setting captured when the review starts unless the command supplies the explicit override:

/pr-review-publish 123 --allow-stale

A matching direct request permits stale publication. Inline comments are always disabled for stale reviews because the original anchors may no longer be valid; the body identifies both the reviewed and current commit. For a qualified fully parsed review, set trusted allowStaleApprovals: true before starting the review to permit an eligible stale APPROVE; authorized non-open publications may also approve when every host gate qualifies them. Degraded Markdown remains COMMENT in every lifecycle state. The session-backed cache survives extension reloads and session resumes and remains bound to the originating session instance and repository.

Optional finding extraction (experimental)

Degraded reviews — incomplete lanes, malformed synthesis — publish a deterministic host-rendered body whose findings were only what the deterministic parser could extract. An experimental opt-in adds one bounded light-tier model call that extracts findings from the review Markdown (including prose the parser cannot read) and merges them after host validation:

{ "extractFindings": true }

Set it in user scope only (~/.pi/agent/pr-review.json); project configuration cannot enable it. Every extracted finding must carry a verbatim quote from the input verified by the host, its claimed path must appear in the input, anchors are re-validated against diff metadata at publication, and extracted severity is display-only — it can never change the verdict line or make a degraded review approve-eligible. Any failure (timeout, malformed output, unverifiable quotes) keeps the deterministic artifact unchanged. Enabling it sends a bounded extraction payload — the review synthesis plus retained heavy-lane evidence gathered from repository context, byte-capped at 256 KiB — to the configured light-tier provider (or the ambient default model when no light tier is configured; the effective model is recorded in each pr-review-extraction entry), which may differ from the provider configured for your heavy lanes.

Outcomes are recorded in session pr-review-extraction entries for the Phase 2 evaluation described in docs/review-quality-plan.md.

Optional verification

You can define fixed test commands in verificationBaselines in the user config. Project config cannot add or override these profiles. The reviewer may select at most one applicable profile and runs it against the exact captured PR head.

{
  "verificationBaselines": {
    "unit": {
      "description": "Run the unit tests",
      "repository": {
        "host": "github.com",
        "owner": "YOUR-ORG",
        "repo": "YOUR-REPO"
      },
      "argv": ["/absolute/canonical/path/to/bun", "test"],
      "platforms": ["darwin", "linux"],
      "totalTimeoutMs": 120000,
      "allowForks": false,
      "acknowledgeUnsandboxedPrCodeRisk": true
    }
  }
}

Profiles require an exact repository identity, a canonical absolute executable, an applicable POSIX platform, a total timeout, and explicit risk acknowledgement. Fork PRs are rejected unless allowForks is true; Windows fails closed.

Risk: verification executes PR code without a filesystem or network sandbox. Cleanup supervises the original POSIX process group, but deliberately detached processes can escape it. Use an external sandbox or container for untrusted PRs.

Verification fetches into extension-owned temporary Git state, checks the exact SHA before and after importing it, runs in a detached worktree with a minimal secret-scrubbed environment, and leaves the user's checkout and FETCH_HEAD unchanged.

Review output

Each finding includes:

• severity: P0, P1, P2, P3, or nit;
• whether it blocks the verdict;
• an explanation and confidence score;
• a diff-anchored file and line range when available.

Severity	Meaning
P0	Drop everything; blocking.
P1	Urgent; blocking.
P2	Normal defect.
P3	Low-priority improvement.
nit	Trivial or optional.

The semantic verdict is request_changes only when a validated P0 or P1 finding exists. Otherwise it is approve or comment. approveMaxPriorityLevel applies equally to fully parsed, complete Markdown and retained strict host-bound JSON: when set to P2, P3, or nit, an otherwise-qualified review whose verdict is approve and whose findings are all at or below that level may publish as APPROVE. GitHub does not permit authors to approve their own PRs, degraded artifacts cannot approve, and a stale approval additionally requires allowStaleApprovals: true.

Setting	Behavior
off (default)	Always COMMENT; never auto-approve.
P2	APPROVE if a fully parsed, complete verdict is approve and all findings are P2/P3/nit.
P3	APPROVE if a fully parsed, complete verdict is approve and all findings are P3/nit.
nit	APPROVE if a fully parsed, complete verdict is approve and all findings are nits.

Configure it with /pr-review-config approve_max_priority_level=P2. To permit an eligible stale review to approve, also set /pr-review-config allow_stale_approvals=true before starting the review. Both settings follow the same user/project overlay pattern as autoPostReviews.

Safety and cost

• review_subagent, review_subagents, and pr_review_verify are exposed only during a direct interactive or RPC /pr-review loop. Extension-generated input cannot authorize them.
• Every review tool also checks an in-memory, session- and cwd-bound loop lease before reading review context, running verification, or spawning a reviewer. Hiding the tools is not the only enforcement boundary.
• Unrelated input, terminal completion, cancellation, session navigation, or tree navigation revokes the lease and aborts in-flight review work. Tools are suspended while a non-open PR waits for confirmation.
• Reviewer subprocesses start with extension discovery disabled, so they cannot recursively invoke this package's agents or verification tool.
• self_review_subagent has separate one-shot authority for an eligible direct top-level task; it cannot authorize review_subagent, review_subagents, or pr_review_verify, and those permissive schemas remain exclusively behind ReviewLoopCoordinator.
• Self-review execute-time checks are authoritative: visibility alone never grants a permit, and consumption hides the tool before any asynchronous delta or child work.
• Reviewers receive the captured diff and are instructed not to modify files.
• The orchestrator does not check out, commit, or push PR code.
• GitHub writes require --comment, an effective autoPostReviews: true setting, the model-free /pr-review-publish command, or a narrowly matched direct interactive/RPC publish request handled by the extension before an agent turn. allowStalePublish controls whether an invocation/config-authorized write may be stale; it does not independently authorize a write.
• Publication authority is captured before review or optional verification begins, so PR code cannot enable it mid-run.
• Multiple model calls run per PR. Use a cheaper light model and reserve stronger models for heavy passes to control cost.
• Same-head review markers prevent duplicate publication by the same GitHub identity.

Development

Run the test suite with:

bun test

The package consists of the /pr-review prompt, tiered subagent and rendering extensions, and supporting libraries under lib/. To use only the prompt template:

cp prompts/pr-review.md ~/.pi/agent/prompts/

Releases use conventional squash-merged PR titles and npm trusted publishing. See RELEASING.md.