PR Review

Caliper runs a multi-phase pipeline on a GitHub pull request, producing findings with severity, category, confidence, and evidence. Findings are posted as inline GitHub comments at the correct file and line locations.

Two modes:

• Interactive — run locally, review each finding, approve/edit/skip before posting
• GitHub Action / CI — lights-out mode (--ci), auto-approves and posts findings

Interactive review

Your first review

npx caliper 42

Replace 42 with your PR number. Caliper will:

1. Fetch the PR and classify files by risk level
2. Show you a file selector to include/exclude files
3. Run convention checks and build architectural context
4. Perform AI code review in batches (with a progress display)
5. Run cross-file synthesis and focused lens passes
6. Show a formatted summary with findings
7. Walk you through each finding for approval before posting

Pipeline phases

Triage — Fetches the PR from GitHub, classifies each changed file as high/medium/low risk, validates PR title and branch naming against your configured patterns, and shows a summary.

File selector (interactive) — After triage, a file selector appears where you can toggle files on/off before the expensive AI phases run. Large or generated files are auto-flagged for exclusion.

Context — Builds architectural context by examining directory structures and reference patterns across changed files. Fetches existing PR comments (for deduplication). Runs deterministic convention checks.

Review — The core AI review phase. Files are grouped into batches and reviewed in parallel. Each batch receives the diff, function context with change annotations, existing findings from convention checks, and your project's policy.

Synthesis — A cross-file pass that catches issues spanning multiple files: consistency problems, missing coordination between related changes, contract mismatches.

Lenses — Domain-expert passes that focus on specific concern areas. Lenses are auto-triggered by risk signals in the code. Available lenses:

Lens	Triggered by
security	Auth-related code, credential handling, session management
data-integrity	Migration files, Prisma schema changes
api-contracts	API directory files, route handlers
concurrency	Mutex, semaphore, lock, atomic, Promise.all, Promise.race, Worker usage
design	Factory/provider/registry patterns, 3+ files in same directory

Consolidate — Deduplicates findings across all phases, removing near-duplicates that target the same file and line range.

Narrative — Generates an AI-written summary that groups findings into design-level issues and line-level issues.

Summary — Formats and displays the full review report with narrative summary, design issues, line-level issues, action plan, and stats footer.

Post — Interactive approval of each finding before posting to GitHub.

The progress TUI

During the review/synthesis/lenses phases, Caliper shows a full-screen progress display with three tabs:

• Progress — Phase status, model being used, token counts, cost estimates, elapsed time
• Findings — Real-time list of findings as they're discovered
• Triage — The triage summary (file list, risk levels, metadata results)

Press Tab to switch between tabs.

Reviewing and posting findings

After the review completes, Caliper presents a findings synopsis then walks you through each finding individually.

Findings synopsis shows severity breakdown, category distribution, file hotspots, confidence distribution, projected review event, and a ranked finding list. Press Enter to proceed or q to skip posting.

Per-finding review shows each finding in a full-screen TUI with the file path, line number, severity, diff context, review comment, and suggested fix. A Details tab shows evidence citations and AI reasoning for low-confidence findings.

Key	Action
y	Approve this finding for posting
n	Skip this finding
e	Edit the finding (opens $EDITOR)
a	Approve all remaining findings
q	Quit — remaining findings stay pending
Tab	Switch between main and details tabs
Arrow left/right	Move between yes/no/edit/all/quit options
Arrow up/down	Scroll within the current tab

Review events

• REQUEST_CHANGES — Used when any blocking finding is approved
• COMMENT — Used when no blocking findings are approved

All approved findings are posted as a single batched GitHub pull request review.

Cross-run deduplication

When you re-run a review on the same PR, Caliper checks for previously posted comments that match current findings and skips duplicates. It also offers to delete stale comments from previous runs.

Resuming interrupted reviews

npx caliper 42 --resume

Loads saved state from /tmp/caliper/42/state.json and continues from the last completed phase.

Post-only mode

npx caliper 42 --post-only

Re-enters the approval flow for a completed review without re-running the AI phases.

Trace viewer

npx caliper trace 42        # Opens trace.html in browser
npx caliper trace 42 --json # Path to raw trace.json

Fast path

Small PRs (< 100 changed lines, ≤ 3 files, no high-risk files) automatically use a fast path that skips synthesis, lenses, consolidation, and narrative.

npx caliper 42 --fast   # Force fast path
npx caliper 42 --full   # Force full pipeline

GitHub Action / CI mode

The --ci flag enables non-interactive mode for CI/CD pipelines. In CI mode, Caliper:

• Skips the interactive file selector and progress TUI
• Auto-approves all findings (no interactive approval flow)
• Filters findings by minimum severity (--min-severity)
• Auto-deletes stale comments from previous runs
• Enforces a cost ceiling (--max-cost)
• Exits 1 on blocking findings (--fail-on-blocking)

npx caliper 42 --ci --min-severity suggestion --max-cost 2.00 --fail-on-blocking

Flag	Description
--ci	Non-interactive mode (auto-approve and post findings)
--min-severity <level>	Minimum severity to post (blocking, suggestion, nit)
--max-cost <amount>	Cost ceiling in USD — skip review if exceeded
--fail-on-blocking	Exit 1 if blocking findings found (for status check enforcement)