Local Code Review

npx caliper review reviews your local changes with AI before you commit — no GitHub PR needed. Run it manually or wire it into a pre-commit hook via npx caliper gate for automatic enforcement. It analyzes staged changes for logic errors, security issues, design problems, and code out of compliance with your repo's established patterns, then presents findings interactively.

Basic usage

npx caliper review

This reviews staged changes and presents findings interactively. Requires ANTHROPIC_API_KEY.

--fix mode

npx caliper review --fix

Auto-applies suggested fixes directly to your working tree files. Each fix is applied in place — review the changes with git diff before committing.

Pre-commit hook (caliper gate)

npx caliper gate

Non-interactive mode designed for git pre-commit hooks. Requires ANTHROPIC_API_KEY. Exits with code 1 if blocking findings are found, code 0 otherwise. No interactive prompts.

To install as a git pre-commit hook, add to .git/hooks/pre-commit:

#!/bin/sh
caliper gate

Variants

Flag	Description
--branch	Review all commits on this branch vs base branch
--pre-push	Review only commits not yet pushed (reads pre-push stdin)
--full	Run full pipeline (synthesis, lenses, consolidation)
--resume	Resume the last review without re-running AI
--fail-on-blocking	Exit 1 if blocking findings are found

Severity filter

npx caliper review --severity blocking   # only report blocking issues

Interpreting results

Severity levels

Level	Meaning
blocking	Must be fixed before merging. Security issues, logic bugs, broken contracts.
recommendation	A concrete improvement worth making. Design improvements, readability, error handling gaps.
nit	Minor style or preference issue. Naming, import order, formatting.

Categories

Listed in priority order (within each severity level):

Category	What it covers
security	Auth guards, injection vulnerabilities, credential exposure, input validation
logic	Off-by-one errors, race conditions, null/undefined handling, edge cases
error-handling	Recovery logic, error propagation, swallowed errors, actionable messages
design	Single responsibility, abstraction level, naming, coupling, duplication
performance	N+1 queries, missing pagination, unbounded operations
boy-scout	Dead code, stale comments, unnecessary complexity in modified code
testability	Missing tests for behavior changes, untestable structure
convention	Project-specific conventions from deterministic checks

Confidence levels

Level	Meaning
high	Strong evidence in the code. The finding is almost certainly correct.
medium	Likely correct based on the diff, but may need human judgment.
low	Possible issue flagged for review. Evidence and reasoning are shown in the Details tab for you to evaluate.

Every AI finding includes evidence (specific file paths, line numbers, or code patterns) and an explanation (the AI's reasoning). These are for your eyes only — they are not posted to the PR.

Feedback history

When you approve or skip findings during interactive review, Caliper records your decisions to .caliper/history.jsonl. Over time, this builds a feedback signal:

• False positive detection — patterns you consistently skip are flagged
• Emerging conventions — patterns you consistently approve are recognized
• Per-category stats — approval rates by category help tune review focus

Run npx caliper stats to see the analysis. See feedback configuration for options.