Hooks Playbook

Here’s the thing about CLAUDE.md: it’s a suggestion. Claude usually follows it, but nothing enforces compliance. Hooks are different. Hooks are code — they execute automatically on specific events and can block, modify, or extend Claude’s behavior. If CLAUDE.md is a polite request, hooks are a locked door.

Official reference — For the full hooks API, event types, and configuration options, see the official hooks docs. This page gives you the five hooks worth setting up first.

The Essential Five

Auto-lint
Block .env
Run tests
Guard config
Auto-format

Run your linter after every file edit so Claude sees and fixes issues immediately.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH 2>&1 || true"
      }
    ]
  }
}

Why: Catches style violations in real-time instead of accumulating them. Claude sees the linter output and self-corrects on the next edit.

Prevent Claude from ever staging sensitive files.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'git add.*\\.env'; then echo 'BLOCKED: Never commit .env files' >&2; exit 1; fi"
      }
    ]
  }
}

Why: CLAUDE.md says “don’t commit .env” — this makes it impossible. The hook exits with code 1, which blocks the action entirely.

Automatically run your test suite after implementation changes.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(ts|tsx|js|jsx)$'; then npm test --silent 2>&1 | tail -5; fi"
      }
    ]
  }
}

Why: Claude gets immediate test feedback and can self-correct without you intervening. The tail -5 keeps output concise.

Warn before Claude edits sensitive configuration files.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -qE '(package\\.json|tsconfig|docker-compose|\\.github/)'; then echo 'WARNING: Editing config file — review carefully' >&2; fi"
      }
    ]
  }
}

Why: Not all files are equal. Config changes have outsized blast radius. This warns but doesn’t block — adjust to exit 1 if you want a hard stop.

Run Prettier (or your formatter) after every write.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}

Why: Keeps diffs clean and prevents style nits in code review. The || true ensures a missing Prettier config doesn’t halt Claude’s workflow.

Where to Configure

Hooks go in your settings files:

File	Scope
`.claude/settings.json`	Team-shared (commit to git)
`.claude/settings.local.json`	Personal (gitignored)
`~/.claude/settings.json`	All your projects

Team hooks (linting, test runs, security blocks) go in .claude/settings.json. Personal preferences go in local or user settings.

Beyond the Essential Five

Official reference — For the full lifecycle event taxonomy, exit code semantics, matcher syntax, and HTTP/agent hooks, see the official hooks docs. Below is the quick map of what’s available.

Hooks fire on 12 lifecycle events — not just PreToolUse and PostToolUse:

Event	When it fires	Use for
`SessionStart`	Session begins (new, resume, or post-clear)	Load context, run diagnostics
`UserPromptSubmit`	Before Claude processes your message	Skill activation, input validation
`PreToolUse`	Before a tool executes	Block dangerous actions
`PermissionRequest`	When Claude requests permission	Automated approval/denial
`PostToolUse`	After a tool executes	Auto-lint, auto-format, run tests
`PostToolUseFailure`	After a tool fails	Error reporting, fallback logic
`SubagentStart` / `SubagentStop`	Agent lifecycle	Agent monitoring, logging
`Stop`	Before Claude finishes responding	Enforce completion conditions (all tests pass, all tasks done)
`PreCompact`	Before context compaction	Backup critical state
`Setup`	During initial setup	Onboarding automation
`SessionEnd`	Session closes	Cleanup, transcript backup

Exit codes: 0 = allow, 1 = block the action, 2 = force Claude to continue (useful for Stop hooks that enforce quality gates). Setup hooks can run in deterministic mode (fast, CI-friendly) or agentic mode (supervised, with diagnostics). HTTP hooks POST events to endpoints instead of running local scripts — useful for centralized logging and remote validation.

Hook Design Principles

Fast hooks only. Hooks run synchronously — a slow hook slows every action. Keep them under 2 seconds.
Fail open for warnings, fail closed for security. Lint warnings shouldn’t block work. .env protection must.
Use || true for non-critical hooks. A crashing linter shouldn’t halt Claude’s workflow.
Test your hooks manually first. Run the command yourself before adding it as a hook.

Overview

Setup

Quick Reference

The Essential Five

Where to Configure

Beyond the Essential Five

Hook Design Principles

Overview

Setup

Quick Reference

​The Essential Five

​Where to Configure

​Beyond the Essential Five

​Hook Design Principles

The Essential Five

Where to Configure

Beyond the Essential Five

Hook Design Principles