review — First-Class Code Review for Agents

Overview

The hard part of AI review is not adding another mode. It is covering the full change, keeping the reviewer independent, requiring evidence, and knowing when fixes are done. @piex-dev/review reduces the human API to one /review. A compact menu selects the default-branch PR scope, working tree, staged changes, a base/commit/file, or a custom focus. Review then begins in an isolated Pi SDK session, and risk routing chooses one reviewer or lead + specialist.

How it works

Review = freeze scope + independent judgment + evidence adjudication. Core insight: more reviewers do not automatically mean more reliable review. Ordinary patches use one reviewer; security, data, concurrency, cross-repo contracts, or large diffs add one specialist, with the lead still responsible for one final report.

/review → choose scope and freeze base/head/diff → physically remove noise
→ create read-only reviewer session → risk route 1→2
→ stream phase, model, thinking level, and tool activity
→ open a safe reviewer transcript on demand
→ submit_review → recheck the diff and refresh once if changed
→ evidence gate → PASS / NEEDS FIX
→ persist finding state for re-review

/review opens one scope menu. The review tool opens no menu, defaults to auto, and retains diff, staged, branch, commit, and file for agents and scripts. An unchanged diff is cached; a changed diff revalidates previous findings first.

Re-review persists a canonical set of open findings. A previous finding closes only when it has a non-empty reason and is classified as resolved, invalid, or superseded; otherwise it remains still_open across later rounds. Duplicate IDs and legacy records are canonicalized to one candidate. The higher-priority candidate wins; confidence breaks ties at the same priority. A previous P0/P1 cannot bypass the blocking gate merely by being resubmitted as P2.

Usage

Install

pi install npm:@piex-dev/review

Source: extensions/review

Prerequisites

The current directory is a git repo (or pass any git repo path via a param); git is on the machine.

Usage

/review
/review ../piex
/review "../piex" "../oh-my-pi"

Pi @path mentions, autocomplete quotes, and relative or absolute paths are accepted. Multi-repo paths are validated and deduplicated by git root; any invalid path aborts with all errors. The default branch is resolved from origin/HEAD, init.defaultBranch, then main/master/trunk. Merge-base calculation is local and never implicitly fetches.

After resolving repositories, the command offers the default-branch PR scope, working tree, staged changes, a custom base, and single-repo commit/file scopes. A custom focus can also be attached to the default PR scope. Commit and file are hidden for linked multi-repo review; every other selected scope applies to all repos. Cancelling the menu or a follow-up input exits without starting a reviewer.

The advanced commit scope compares the target commit with its first parent, so a merge commit shows only what that merge introduced relative to that first parent. A root commit is reviewed against Git's empty tree.

• NEEDS FIX: at least one evidence-backed P0/P1; fix it, then run /review again
• PASS: no blocking findings; P2 is advisory and does not require another loop
• cached: scope and diff are unchanged, so no reviewer call is repeated

Live progress and reviewer transcript

Interactive TUI /review runs show only the live panel above the editor, avoiding duplicate status-bar output. Other UI modes fall back to a compact status summary:

Review · 00:31 · reviewing
● lead · openai-codex/gpt-5.6-sol · thinking xhigh · fast · reading src/reviewer.ts · 3 tools
● specialist/security · openai-codex/gpt-5.6-sol · thinking max · fast · reasoning about changes · 2 tools

The panel updates across preparing, reviewing, adjudicating, and validating, including a changes detected; restarting phase, as well as source reads, searches, frozen diff inspection, and report submission. During parallel execution, a finished reviewer immediately shows ✓ … done without waiting for its peer, and trailing events cannot change it back to running. Tool callers receive the same structured snapshot through onUpdate, and the final report retains the actual reviewer model, thinking level, and Fast mode state. When enabled, progress, transcript, and the final report all show fast.

After the reviewers finish, the extension recaptures the same diff. If its hash changed, the first result is discarded and the review automatically restarts once against the latest snapshot, updating both progress and transcript scope metadata while retaining only the latest attempt's reviewer state. It fails only if the diff keeps changing during the second attempt, preventing stale reports without requiring a manual rerun after a single concurrent save or formatter pass.

In the interactive TUI, /review runs in the background and immediately returns the input editor. During a running review, enter /review-log or press Ctrl+Alt+R; either opens a full-window, live, scrollable transcript overlay. After completion, run /review-log again to reopen the latest record. The overlay reuses the active Pi theme's semantic colors from the main agent. Headers, phases, tool titles, and prompt metadata use the matching accent, muted, success/error, and tool-title tokens. Embedded prompt diffs and review_diff use added/removed/context colors. JSON keys, numbers, and punctuation receive lightweight highlighting, while long string values use the main agent's toolOutput text color instead of becoming a large red block. read output is highlighted according to file extensions such as TypeScript, Python, and Rust. Unknown extensions keep the normal code color instead of using unreliable auto-detection. Use Tab to switch between lead and specialist, arrow keys or j/k to scroll, G to return to the end and resume live follow, and q/Esc to close.

The transcript records task prompts, visible assistant text, tool calls and bounded result summaries, phase/retry status, and the final submit_review. Raw thinking/reasoning is not collected. Secret/token/password fields and common credential formats are redacted before entering memory, and text, serialized values, collection depth, entry count, and rendered lines are bounded. The record is neither added to the author's main session nor written to disk; /reload or process exit clears it.

Large tool results are truncated inside JSON values with a [TRUNCATED] marker, keeping the JSON valid so retained source and diff content still highlights with its original line breaks. The overlay caches highlighting and wrapping per entry, processing only changed content during streaming. Activity from the other reviewer does not invalidate the selected view. Width changes only rewrap content; theme refreshes clear the cache, and evicted log entries release their cached rendering.

Optional configuration

The current model is used by default. To pin a reviewer or enable Fast mode, create ~/.pi/piex-dev/review/settings.json:

{
  "model": "openai-codex/gpt-5.6-sol",
  "thinkingLevel": "xhigh",
  "fastMode": true,
  "specialistModel": "openai-codex/gpt-5.6-sol",
  "specialistThinkingLevel": "max",
  "specialistFastMode": true,
  "maxReviewers": 2
}

thinkingLevel and specialistThinkingLevel independently control the lead and specialist and accept Pi levels from off through max; the specialist inherits the lead level when omitted. Explicit model / specialistModel settings always take precedence; a re-review retains the original reviewer model only when the corresponding setting is absent. maxReviewers accepts only 1 or 2.

fastMode controls the lead, while specialistFastMode controls the specialist and inherits fastMode when omitted. When set to true, the extension injects service_tier: "priority" into that isolated reviewer's request. This is supported only for the openai-codex provider using the openai-codex-responses API with ChatGPT OAuth and the gpt-5.4, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, or gpt-5.6-luna, gpt-6-astra model. Other combinations fail with a configuration error before reviewer startup instead of silently falling back. Reviewer sessions do not inherit the outer /gpt-fast state, so configure these fields explicitly. The fast label confirms that request injection is enabled, not that the server accepted the tier; Pi's local cost telemetry may still use standard-tier estimates, while backend quota accounting remains authoritative.

Note: ultra is not a Pi thinking level. The GPT-5.6 Sol model page lists max as the highest API reasoning.effort; Codex Ultra uses maximum reasoning and may also run additional agents, as described in the OpenAI model guidance. Therefore, max is the highest setting this extension can pass to an individual reviewer, not the complete Codex Ultra mode. An ultra value is ignored.

Verify

pi -e ./extensions/review/src/review-v2.ts -p "what is 1+1" --no-session

Implementation

Scope, diff parsing, reviewer orchestration, finding gates, session state, and rendering are separate modules. Noise is physically removed at the diff-chunk layer; scope freezes base/head OIDs and changed ranges. After a reviewer returns, the diff hash is captured again. One change triggers a bounded restart against the latest snapshot; continued changes stop the run so it cannot return a stale report or consume models indefinitely. Every reviewer is a fresh in-memory session with extensions, skills, templates, themes, and automatic system/context injection disabled. Repository guidance is read explicitly through read-only tools, so it cannot replace the reviewer system role. It only receives read/grep/find/ls, the exact frozen-patch review_diff tool, and typed submit_review. The reviewer is explicitly required to call it as the only tool in the final tool batch; a successful submission returns terminate: true, ending that batch without an extra model request. The reviewer cannot write files or execute commands.

The main workflow subscribes to lifecycle, message-type, and tool execution events from every isolated session and reduces them into reviewer-scoped progress snapshots. Parallel lead and specialist activity cannot overwrite each other. A terminal state ignores trailing activity; only an explicit adjudication run can reactivate the lead. A one-second heartbeat keeps elapsed time moving during long reasoning periods. Paths are stripped of control characters and truncated before display; grep patterns, thinking deltas, and text deltas never enter compact progress output.

The same event stream also feeds a separate bounded in-memory transcript store. Only visible text_delta content is merged by reviewer and stage; thinking_delta is explicitly discarded, while tool arguments and results are redacted and truncated first. Every run has an ID, so late events from an old run cannot contaminate a newer review. The TUI overlay subscribes to store changes, pauses live follow when scrolled away from the end, and resumes it on return.

Interactive /review runs the long review as a managed background task so Pi's main input loop becomes available immediately and can dispatch /review-log while the review is active. The task uses its own AbortSignal; session_shutdown cancels it and waits for reviewer cleanup on exit, /reload, or session replacement. The command and tool entrypoints still share one execution gate, so they cannot write to the same transcript concurrently.

Diff file paths are matched against repository-relative paths first. A leading a/ or b/ is interpreted as Git's display prefix only after an exact match fails, so real top-level a and b directories cannot be mapped to the wrong file.

The evidence gate requires a finding to belong to the frozen repo/file, overlap a changed hunk, be patch-introduced, and include trigger/impact/evidence. Confidence must be at least 0.8 for P0/P1 and 0.75 for P2; previous blocking findings are checked against their effective retained priority. Candidates are canonicalized by stable ID and semantic key. The verdict and summary are generated from gated current and open findings rather than copied from the reviewer's raw summary. Only security, data, concurrency, cross-repo, or large diffs route to a second specialist. Lead and specialist run in parallel; the lead adjudicates one final report.

Design notes

Core trade-off: simplicity is the external API; orchestration complexity stays inside. /review exposes one scope-selection layer while risk routing retains control of reviewer, model, and adjudication details.

Changelog

Roadmap

Version history