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

Here's what a posted finding looks like on GitHub:

C

caliper-aicommented 2 minutes ago

blocking

src/orders/checkout.ts, line 47

Missing await on database write — order silently not saved

db.orders.insert(order) returns a Promise, but the result isn't awaited. The customer sees a confirmation page, but the order never persists.

Suggested fix

db.orders.insert(order);

await db.orders.insert(order);

Found by Caliper

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

Findings are always posted as a COMMENT review — they never block the PR via GitHub's review mechanism. Severity labels in each comment ([BLOCKING], [RECOMMENDATION], [NIT]) signal importance.

In CI mode, --fail-on-blocking exits with code 1 if blocking findings exist — use this with branch protection rules to enforce merge gates.

All approved findings are posted as a single batched GitHub pull request review. Your approval/skip decisions are recorded to .caliper/history.jsonl for feedback analysis (see caliper stats).

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 automatically skip expensive phases (synthesis, lenses, consolidation, narrative) when all thresholds are met: < 100 changed lines, ≤ 3 files, and no high-risk files.

Tune the thresholds in .caliper/config.yaml:

fastPath:
  maxChangedLines: 200
  maxFiles: 5
  maxHighRiskFiles: 1

Or override per-run:

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 recommendation --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, recommendation, 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)