Getting Started

By the end of this page you'll have Caliper enforcing your conventions after every Claude Code turn — in about 30 seconds.

Install

npm install --save-dev @caliperai/caliper

Using pnpm

pnpm add -D @caliperai/caliper

Install globally instead

npm install -g @caliperai/caliper
# then use caliper instead of npx caliper

You'll need Node.js 20+. That's the only prerequisite for convention enforcement.

Step 1: Initialize

npx caliper init

Requires ANTHROPIC_API_KEY to be set. This single command does everything automatically — zero prompts:

1. Auto-detects your framework (TypeScript, Python, Go, Ruby, Rust, Java) and creates .caliper/ with your project configuration and review policy
2. Compiles your CLAUDE.md conventions into deterministic checks
3. Installs all three hooks — Claude Code stop hook, git pre-commit hook (npx caliper gate), and git pre-push hook (npx caliper review --pre-push)
4. Adds a prepare script to package.json so teammates get hooks automatically on pnpm install
5. Generates a GitHub Actions workflow (if a GitHub remote is detected) for automated PR review
6. Runs your first convention checks — shows what Caliper found right away

export ANTHROPIC_API_KEY="sk-ant-..."

Add the key to your shell profile (.zshrc, .bashrc) so it persists across sessions.

For interactive setup with full control over preferences, model selection, and project standards:

npx caliper init --interactive

What happens under the hood: Caliper reads your CLAUDE.md and turns prose rules into checks:

Your CLAUDE.md says	Compiled check
"No classes — use functions and plain objects"	grep — flags class declarations
"Keep functions under ~30 lines"	AST — measures each function's length
"Never use execSync with template strings"	grep — flags execSync( calls
"Every migration needs a test file"	file-exists — ensures .test.ts companion
"Catch blocks must not swallow errors silently"	ai-check — AI evaluates each catch match

Rules that need judgment but have a locatable code anchor become ai-check checks — a regex finds the candidate code, then a focused AI question evaluates each match. Rules with no code anchor at all ("use meaningful error messages") become conventions for the AI review layers. Nothing is dropped.

That's it. From now on, every time Claude Code finishes a turn, Caliper runs your compiled checks. Violations exit with code 2, which tells Claude to fix them before continuing. Sub-second, no AI calls, zero false positives.

---

What's next

Convention enforcement catches mechanical violations with no AI calls. AI review catches the bugs that matter most — missing awaits, race conditions, security holes, and code that's drifted from your repo's established patterns.

Local AI review

Review staged changes before you commit. Catches logic errors, security issues, design problems, and code out of compliance with your repo's patterns — things deterministic checks can't catch.

npx caliper review

Requires ANTHROPIC_API_KEY.

Auto-apply fixes:

npx caliper review --fix

Block bad commits with a git hook:

npx caliper gate

Full local review guide →

PR review

Full multi-phase pipeline that posts findings as inline GitHub comments. Runs specialized lenses for security, data integrity, API contracts, concurrency, and design.

npx caliper 42          # interactive — review each finding before posting
npx caliper 42 --ci     # CI mode — auto-approve and post

Requires ANTHROPIC_API_KEY + GitHub CLI (gh).

Installing and authenticating GitHub CLI

# macOS
brew install gh

# Then authenticate
gh auth login

See cli.github.com for other platforms.

Full PR review guide →

Review history

As you use npx caliper review and PR reviews, your approval/skip decisions are recorded. Analyze patterns over time:

npx caliper stats

Shows approval rates by category, false positive patterns, and emerging conventions. See feedback configuration.

---

Customizing your setup

npx caliper init uses auto-detected defaults. For full control over every setting:

npx caliper init --interactive

This walks you through framework presets, source directories, toolchain commands (format, lint, test), AI model selection, review preferences (tone, strictness, nit policy), and project standards (testing, error handling, complexity thresholds).

All configuration lives in .caliper/config.yaml. See the configuration reference for every option.

Re-generating checks

Whenever your CLAUDE.md conventions change, re-run:

npx caliper refresh

Caliper also checks for staleness automatically at the start of each PR review and re-generates if needed.

Badge

Add a badge to your README to show your repo uses Caliper for convention enforcement.

[![Caliper](https://img.shields.io/badge/enforced_by-Caliper-blue)](https://getcaliper.dev)