Configuration

All Caliper configuration lives in .caliper/ at your repo root.

File	Purpose	How it's created
config.yaml	Project configuration	npx caliper init (you can customize)
policy.md	Review policy the AI evaluates against	npx caliper init (you can customize)
conventions.yaml	Generated judgment-based conventions	npx caliper refresh (auto-generated)
history.jsonl	Finding feedback history (gitignored)	Auto-created during reviews

config.yaml reference

Project structure

Field	Type	Default	Description
preset	string	auto-detected	Framework preset: typescript, python, go, ruby, rust, java
srcDirs	string[]	["src"]	Directories containing source code
excludeDirs	string[]	["node_modules"]	Directories to exclude from scanning
fileIncludes	string[]	all supported	Glob patterns for source files

File classification

Field	Type	Default	Description
baseBranch	string	"main"	Base branch for npx caliper review --branch diffing
excludeFiles	string[]	["\\.lock$", "\\.snap$"]	Regex patterns for files to exclude from review
fileTypePatterns	map	{}	Regex patterns mapping file paths to type labels (e.g., api-route, component, test)
riskPatterns	object	see below	Regex patterns for classifying files as high/medium/low risk

Default risk patterns:

• high: auth/, migrations?/, schema.prisma, /api/
• medium: /lib/, config\.[^/]+$
• low: .test., .spec., .md, .css, .json, docs/

Example:

fileTypePatterns:
  api-route: "^(?:app|src)/api/.+/route\\.[jt]sx?$"
  component: "^(?:app|src)/.+\\.(tsx|jsx)$"
  test: "\\.(?:test|spec)\\.[jt]sx?$"

riskPatterns:
  high:
    - pattern: "auth/"
      reason: auth/security file
    - pattern: "migrations?/"
      reason: schema/migration change
  medium:
    - pattern: "/lib/"
      reason: library code
  low:
    - pattern: "\\.test\\.[^/]+$"
      reason: test file

Validation patterns

Field	Type	Default	Description
prTitlePattern	string (regex)	none	Regex for validating PR titles (e.g., conventional commits)
branchPattern	string (regex)	none	Regex for validating branch names

Example:

prTitlePattern: "^(feat|fix|chore|docs|refactor|test|ci|build|perf|style)(\\(.+\\))?!?: .+"
branchPattern: "^(feat|fix|chore|docs|refactor|test|ci|build|perf|style)/.+"

Toolchain

Field	Type	Default	Description
toolchain.format	string	none	Format check command
toolchain.lint	string	none	Lint command
toolchain.test	string	none	Test command

Example:

toolchain:
  format: npm run format:check
  lint: npm run lint
  test: npm test

AI model

Field	Type	Default	Description
model	string or object	{ small: "haiku", medium: "sonnet", large: "opus" }	Claude model(s) for AI review phases

Shorthand — use one model for everything:

model: sonnet

Expanded — three semantic slots:

model:
  small: haiku # Quick, mechanical tasks (consolidation, small-PR triage)
  medium: sonnet # Standard review work
  large: opus # Deep architectural reasoning (large/complex PRs only)

The system picks which slot to use based on the phase and PR scope.

Model selection strategy

Caliper uses three model slots (small, medium, large) and selects which to use based on:

PR scope classification:

• small — <100 changed lines, ≤3 files, no high-risk files
• normal — everything in between
• large — >500 changed lines, >10 files, or 3+ high-risk files

Phase-to-slot mapping:

Phase	Small PR	Normal PR	Large PR
Review	medium	medium	large
Synthesis	medium	medium	large
Crossfile select	small	small	small
Lenses	medium	medium	large
Consolidate	small	medium	medium
Narrative	small	medium	medium

Lenses

Field	Type	Default	Description
lenses	string[]	["security"]	Lens passes to always run (in addition to auto-triggered lenses)

Available lenses: security, data-integrity, api-contracts, concurrency, design.

Lenses run automatically when risk signals are detected:

• File path triggers: Migration paths trigger data-integrity; API directories and route files trigger api-contracts; factory/provider/registry files trigger design
• Diff content triggers: Concurrency primitives trigger concurrency; auth-related keywords trigger security; factory/provider patterns trigger design
• Structural triggers: 3+ changed files in the same directory triggers design

Auto-triggered lenses are merged with configured lenses — no duplicates.

lenses:
  - security
  - api-contracts

Fast path

Small PRs automatically skip expensive phases (synthesis, lenses, consolidation, narrative) to save time and cost. Override with --fast (always skip) or --full (never skip).

Field	Type	Default	Description
fastPath.maxChangedLines	number	100	Max added+deleted lines to qualify for fast path
fastPath.maxFiles	number	3	Max non-excluded, non-deleted files
fastPath.maxHighRiskFiles	number	0	Max high-risk files (auth, migrations, API routes)

A PR qualifies for fast path when all three conditions are met. When fast path activates, only context → review → summary → post phases run.

# Relax thresholds for a repo with many small PRs
fastPath:
  maxChangedLines: 200
  maxFiles: 5
  maxHighRiskFiles: 1

Advanced tuning

Field	Type	Default	Description
costWarningThreshold	number	2	Maximum estimated cost (USD) before prompting for confirmation. Set high to disable.
crossfileContextBudget	number	12000	Token budget for cross-file context in synthesis

Review preferences

Field	Type	Default	Options
preferences.tone	string	"direct"	"direct" — no hedging; "friendly" — softer phrasing; "terse" — minimal words
preferences.strictness	string	"precise"	"precise" — only bugs and clear mistakes; "balanced" — also readability and design; "thorough" — everything including style
preferences.nits	boolean	true	Whether to report nitpicks (spacing, naming, import order)
preferences.suggestedFixes	string	"always"	"always" — diff for every finding; "when-clear" — only obvious fixes; "never" — describe only

Project standards

Field	Type	Default	Options
standards.testing	string	"complex-only"	"always" — flag any untested function; "complex-only" — only complex logic; "none"
standards.documentation	string	"complex-only"	"public-api" — require docs on exports; "complex-only" — only non-obvious logic; "none"
standards.errorHandling	string	"important-paths"	"strict" — flag unhandled rejections, empty catches; "important-paths" — I/O, auth, payment; "discretionary"
standards.complexity	string	"moderate"	"strict" — flag long functions, deep nesting; "moderate" — only hard to follow; "none"
standards.logging	string	"important-paths"	"strict" — log every state change; "important-paths" — error handlers and key ops; "none"
standards.dependencies	string	"justified"	"strict" — flag every new package; "justified" — only if it duplicates existing; "open"
standards.magicValues	string	"non-obvious"	"strict" — flag any raw number/string; "non-obvious" — allow 0, 1, ''; "none"
standards.deadCode	string	"strict"	"strict" — unused imports, unreachable branches, commented-out code; "comments-only" — only commented-out blocks; "none"

Feedback loop

Field	Type	Default	Description
feedback.enabled	boolean	true	Record finding feedback to .caliper/history.jsonl
feedback.autoCalibrate	boolean	false	Automatically inject feedback patterns into AI review prompts
feedback.maxHistory	number	10000	Maximum history entries to retain (oldest are truncated)
feedback.minEvidence	number	5	Minimum occurrences before a pattern is reported by npx caliper stats

Example:

feedback:
  enabled: true
  autoCalibrate: false
  maxHistory: 10000
  minEvidence: 5

When enabled, every finding you approve or skip during npx caliper review and npx caliper <pr-number> is recorded to .caliper/history.jsonl. Run npx caliper stats to analyze patterns — false positives, emerging conventions, and per-category approval rates.

When autoCalibrate is enabled, historical feedback patterns are injected into AI review prompts to raise the confidence bar on frequently-rejected finding types.

Conventions and policy customization

.caliper/policy.md — The review policy defines what the AI evaluates against: priority order, engineering criteria, design criteria, and risk classification. You can customize this to match your team's standards.

Regenerating checks

When your CLAUDE.md files change, regenerate the deterministic checks:

npx caliper refresh

Caliper automatically checks for staleness at the start of each PR review and auto-refreshes if artifacts are out of date.