Getting Started

By the end of this page you'll have Caliper enforcing your conventions after every Claude Code turn — for free, in about two minutes.

Install

Caliper is a private npm package. You'll need an access token — if you don't have one yet, join the waitlist and we'll send one over.

1. Configure npm access

Create an .npmrc file in your repo root:

@caliperai:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Then set the token in your environment:

export NPM_TOKEN=YOUR_TOKEN_HERE

Add this to your shell profile (.zshrc, .bashrc) so it persists. For CI, add NPM_TOKEN as a secret in your CI environment.

2. Install the package

npm install --save-dev @caliperai/caliper

Using pnpm

pnpm add -D @caliperai/caliper

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

Step 1: Scaffold your config

npx caliper init --yes

Caliper auto-detects your framework (TypeScript, Python, Go, Ruby, Rust, Java) and creates a .caliper/ directory with your project configuration and review policy. You can customize everything later with npx caliper init (interactive mode).

Step 2: Compile your conventions

npx caliper refresh

This reads your CLAUDE.md files and compiles every mechanically-enforceable rule into a deterministic check. Requires ANTHROPIC_API_KEY for this one-time step — the compiled checks run free from here on.

Don't have an API key yet?

Get one at console.anthropic.com, then:

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

Add this to your shell profile (.zshrc, .bashrc) so it persists.

What happens under the hood: Caliper reads your CLAUDE.md and turns prose rules into one of six check types:

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

Rules that need judgment ("use meaningful error messages") become conventions for the AI review layers. Nothing is dropped.

Step 3: Install the stop hook

npx caliper init --agent

This adds a Claude Code stop hook to .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx caliper check --agent",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

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, zero cost, zero false positives.

---

What's next

Convention enforcement is the tightest loop — it catches the most issues at the lowest cost. But Caliper has two more layers for deeper review.

Local AI review

Review staged changes before you commit. Catches logic errors, security issues, and design problems that deterministic checks can't.

npx caliper check

Requires ANTHROPIC_API_KEY. Costs ~$0.05–$0.30 per review.

Auto-apply fixes:

npx caliper check --fix

Block bad commits with a git hook:

npx caliper check --hook

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). Costs ~$0.20–$2.00 per review.

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 →

---

Customizing your setup

The --yes flag in step 1 used auto-detected defaults. To configure everything interactively:

npx caliper init

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.