What are Hooks?

Hooks are event-driven scripts that fire on specific lifecycle events during a Claude Code session. They run shell commands (bash, Python, Node.js) in response to events like tool calls, session stops, or user prompts.

Think of hooks as middleware — they intercept events and can warn, block, or augment behaviour automatically.

Hook Events

sequenceDiagram
  participant You
  participant Claude
  participant Tool
  participant Hook
  You->>Hook: UserPromptSubmit
  You->>Claude: Send message
  Claude->>Hook: PreToolUse
  Hook-->>Claude: allow / block
  Claude->>Tool: Execute tool
  Tool-->>Claude: Result
  Claude->>Hook: PostToolUse
  Claude->>You: Response
  Claude->>Hook: Stop

Configuration

Hooks are configured in your Claude Code settings (.claude/settings.json or global settings):

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

This plays a sound effect every time Claude finishes a response — useful so you don't have to watch the terminal.

The Verification Loop

The most impactful hook pattern is using PostToolUse to create a verification loop: after every file edit, automatically run tests or linting. Claude sees the results in context and self-corrects immediately.

{
  "PostToolUse": [{
    "matcher": "Edit",
    "hooks": [{
      "type": "command",
      "command": "npx eslint --fix $FILE_PATH"
    }]
  }]
}

Boris Cherny uses a similar pattern: a PostToolUse hook that runs bun run format || true after every edit. The || true ensures the hook doesn't block Claude if formatting fails — it just applies what it can.

This creates a tight feedback loop: Claude edits → formatter runs → Claude sees the result → adjusts its next edit accordingly. Quality improves automatically without you intervening.

More Practical Examples

Notification when Claude needs you

{
  "PermissionRequest": [{
    "hooks": [{
      "type": "command",
      "command": "say 'Hey! I need your permission'"
    }]
  }]
}

Run tests after edits

{
  "PostToolUse": [{
    "matcher": "Edit",
    "hooks": [{
      "type": "command",
      "command": "npm test --silent 2>/dev/null || echo 'WARNING: Tests failed after edit'"
    }]
  }]
}

Claude gets immediate feedback — if an edit breaks tests, the warning appears in context and Claude can self-correct.

Security Hooks

One of the most powerful applications is blocking edits to sensitive files. The PreToolUse event can reject tool calls before they execute:

{
  "PreToolUse": [{
    "matcher": "Edit",
    "hooks": [{
      "type": "command",
      "command": "echo $FILE_PATH | grep -q 'src/core/auth\\|src/core/billing\\|.env' && echo 'BLOCKED: This file requires manual review' && exit 2 || exit 0"
    }]
  }]
}

Exit code 2 tells Claude Code to reject the tool call. Claude can still read these files — it just can't modify them. Your team edits auth, billing, and environment files manually.

Hooks vs Other Building Blocks

The key distinction: hooks run shell scripts, while commands and skills provide instructions for Claude. Hooks are the only building block that executes code outside of Claude's model.

Key Takeaway

Hooks are the automation layer — they react to events without you typing anything. The verification loop (PostToolUse hooks that test or lint after edits) is the single most valuable hook pattern, creating automatic quality feedback that compounds with every session.