Review Pro+

Overview

bpsai-pair review dispatches up to three specialized agents against a diff and returns a structured verdict: approve, comment, or request changes. It works on pull requests, task changes, or the current branch. The review pipeline runs agents in read-only mode so they can analyze code without modifying it.

# Review a PR
bpsai-pair review pr 146

# Review the current branch before opening a PR
bpsai-pair review branch

# Let the CLI figure out what you mean
bpsai-pair review auto 146

Every review produces a verdict based on the combined findings from all dispatched agents. The exit code reflects the verdict, making it suitable for CI pipelines where a non-zero exit blocks merges.

Subcommands

review pr <number>

Review a GitHub pull request by its number. Fetches the PR diff from GitHub and dispatches review agents against it.

# Review PR #146
bpsai-pair review pr 146

# Review and post findings as a GitHub review comment
bpsai-pair review pr 146 --post

# Get structured JSON output for CI
bpsai-pair review pr 146 --json

review task [<task_id>]

Review changes associated with a task. If a task ID is provided, reviews the diff for that task. If omitted, reviews uncommitted changes in the working tree.

# Review a specific task's changes
bpsai-pair review task T18.3

# Review uncommitted changes
bpsai-pair review task

# JSON output
bpsai-pair review task T18.3 --json

review branch [--base <branch>]

Pre-PR validation. Reviews the full diff of the current branch against the base branch. The base is auto-detected (prefers dev, falls back to main) but can be overridden.

# Review current branch against auto-detected base
bpsai-pair review branch

# Review against a specific base branch
bpsai-pair review branch --base main

# JSON output
bpsai-pair review branch --json

review auto [<query>]

Auto-routes the review request to the correct subcommand based on the query. Useful when you do not want to remember which subcommand to use.

# Routes to "review pr 146"
bpsai-pair review auto 146

# Routes to "review task T18.3"
bpsai-pair review auto T18.3

# Routes to "review branch" (no query or ambiguous)
bpsai-pair review auto

The routing logic classifies the query by pattern:

Agent Pipeline

The review system dispatches up to three specialized agents. Each agent runs in plan permission mode with read-only tool access (Read, Glob, Grep). They receive the raw diff text and analyze it independently.

Nayru and Laverna are dispatched on every review. Vaivora is dispatched only when the diff exceeds the large-diff thresholds (see below). All agents produce findings classified by severity.

Diff Size Thresholds

When a diff is large enough that cross-module interactions become a concern, Vaivora is automatically added to the review pipeline. The thresholds are:

Either threshold triggers Vaivora. A diff with 200 changed lines across 15 files will trigger it, as will a diff with 600 changed lines in 3 files.

Findings Classification

Each agent classifies its findings into three severity levels:

Findings from all agents are combined into a single verdict:

CI Integration

The --json flag and exit code behavior make bpsai-pair review suitable for CI pipelines. Use it as a merge gate or an automated review step.

GitHub Actions Example

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PairCoder
        run: pip install bpsai-pair
      - name: Run review
        run: bpsai-pair review pr ${{ github.event.pull_request.number }} --post --json
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

JSON Output Structure

When using --json, the output contains:

{
  "action": "approve",
  "findings": "## Review Summary\n...",
  "errors": 0,
  "agents": ["reviewer", "security-auditor"],
  "lines_changed": 142,
  "files_changed": 5,
  "dispatched": true
}

An empty diff returns "action": "skipped" with a "reason": "empty_diff" field and exit code 0.

The --post Flag

Available on the review pr subcommand. When set, the combined findings are posted as a GitHub review on the PR using the gh CLI.

• The review body is prefixed with [Automated Review - bpsai-pair]
• The body is capped at 60,000 characters
• The review type maps directly from the verdict: approve, comment, or request_changes
• Requires gh to be installed and authenticated (gh auth login)

Examples

# Quick review of a PR
bpsai-pair review pr 146

# Review and post to GitHub
bpsai-pair review pr 146 --post

# Pre-PR branch review against main
bpsai-pair review branch --base main

# Review current task's changes
bpsai-pair review task T18.3

# Auto-route with JSON output for scripts
bpsai-pair review auto 146 --json

# CI gate: exit 1 blocks merge if changes requested
bpsai-pair review pr $PR_NUMBER --json || exit 1

Error Handling

• If all agents fail, the action is set to error and exit code is 1
• If some agents fail, the review continues with the successful agents' output
• An empty diff returns skipped with exit code 0