pi-review

Pi extension that adds a local, read-only code review workflow:

• Run /review to start a one-shot review turn.
• Temporarily limits tools to read-only inspection tools and blocks mutating shell commands while review mode is active.
• Raises thinking to high by default, or to the effort level supplied in the command.
• Injects review-specific instructions so output is findings-first and actionable.
• Restores the previous tools, thinking level, and footer status after the review turn ends.

Install

From npm after the package is published:

pi install npm:@bacnh85/pi-review

From this repository checkout:

pi install ./extensions/pi-review

For local development without installing:

pi -e ./extensions/pi-review

Commands

Command	Description
/review	Run a local read-only review. In TUI, choose a review scope; otherwise review branch changes plus staged, unstaged, and untracked files.
/review high <target or instructions>	Run with an explicit effort level and target/focus.

Supported effort tokens are off, minimal, low, medium, high, and xhigh.

Workflow examples

/review
/review xhigh main...my-feature
/review focus on auth/session security regressions

During review mode, Pi can inspect repository state with read-only commands such as git status --short, git diff, git diff --cached, and git ls-files --others --exclude-standard. It should then read relevant source files before reporting findings.

Output contract

Review output is intentionally high-signal:

• Lead with findings, ordered by severity.
• For each finding include severity, file:line, issue, why it matters, and suggested fix.
• Cite the code evidence inspected.
• Avoid praise and broad summaries unless there are no findings.
• If no actionable issues are found, say No findings and briefly list the scope inspected.

Severity guidance:

• Important: likely correctness, security, data-loss, or regression issue introduced by the reviewed change.
• Nit: minor cleanup only if requested or clearly useful.
• Pre-existing: issue found in surrounding code but not introduced by the reviewed change.

Safety and read-only behavior

pi-review is designed for local review, not automatic fixing. While review mode is active, it limits active tools to read, bash, grep, find, and ls, and rejects shell commands that are likely to mutate files, git state, packages, processes, permissions, or editor sessions.

Shell-command blocking is heuristic. Some apparently read-only commands can still write caches or logs, and some legitimate review commands may be blocked conservatively. RTK-wrapped inspection commands such as rtk git diff are allowed only when the wrapped command matches the same read-only allowlist; mutating wrapped commands remain blocked.

Review guidance files

Pi already loads general repository guidance from AGENTS.md according to its normal instruction flow. For review-only guidance, add a top-level REVIEW.md; when present, pi-review injects its content as highest-priority review guidance for the review turn.

Design notes

/review is implemented as an extension command rather than a prompt template or skill because it needs runtime behavior: tool gating, status UI, thinking-level changes, and automatic restoration. The behavior is inspired by Codex's dedicated local /review flow and Claude Code's findings-focused code review, but v1 deliberately stays read-only and local. It does not post GitHub comments, run PR checks, or apply fixes.

Packaging and release

package.json declares this as a Pi package with the pi-package keyword and a pi.extensions entry for ./index.ts. Runtime Pi imports are listed as peer dependencies per Pi package guidance.

The repository publish workflow includes extensions/pi-review. Bump the package version in package.json when publishing a new npm release; the CI workflow only publishes packages whose versions changed, or the selected package from manual workflow_dispatch.