The Hooks System

Hooks are lifecycle callbacks that fire at specific points during Claude’s execution — before a tool runs, after a file is edited, when a session starts, and 19 other moments. With 22 event types and 4 handler types (command, HTTP, prompt, agent), hooks are the deepest extensibility point in the CLI. This chapter is the full configuration reference; for security-focused patterns like blocking destructive commands, see the Hooks as Guardrails chapter.

Event Types

Every hook targets one of 22 events. Each event fires at a specific moment in Claude’s lifecycle and optionally supports a matcher to narrow scope.

Handler Types

Each hook entry specifies one of four handler types that determine how the hook runs.

Command Handler

The most common handler type. The shell command receives hook context on stdin as JSON and communicates its decision via exit codes.

{
  "type": "command",
  "command": "./.claude/hooks/validator.sh",
  "timeout": 600,
  "async": false,
  "statusMessage": "Validating..."
}

• command (required): shell command to run
• timeout (optional): seconds before cancel, default 600
• async (optional): run in background without blocking Claude
• statusMessage (optional): spinner text shown during execution

HTTP Handler

Posts the JSON input to an external endpoint. Headers support environment variable interpolation with $VAR_NAME syntax, but only for variables listed in allowedEnvVars.

{
  "type": "http",
  "url": "http://localhost:8080/hooks/validate",
  "headers": {"Authorization": "Bearer $MY_TOKEN"},
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 30
}

Prompt Handler

Delegates the decision to a Claude model. The $ARGUMENTS placeholder in your prompt text is replaced with the full JSON input from the hook event.

{
  "type": "prompt",
  "prompt": "Should this bash command run? $ARGUMENTS\n\nDeny commands with 'rm -rf'.",
  "model": "claude-3-5-haiku-20241022",
  "timeout": 30
}

Agent Handler

Spawns a full subagent with tool access. Use this when evaluation requires reading files, running commands, or multi-step reasoning.

{
  "type": "agent",
  "prompt": "Verify this operation is safe: $ARGUMENTS",
  "timeout": 60
}

Configuration

Hooks are defined in settings.json under the hooks key. The structure nests event name, then an array of matcher+hooks pairs, then an array of handler objects within each pair.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/block-rm.sh"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-edit.sh",
            "timeout": 10,
            "statusMessage": "Validating edit..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/run-linter.sh",
            "timeout": 30,
            "statusMessage": "Running linter..."
          }
        ]
      }
    ]
  }
}

Configuration Scopes

Hooks can be defined at multiple levels, from personal defaults to project-specific rules.

The /hooks Browser

Inside an interactive Claude session, type /hooks to open the built-in hook browser. It lists all registered hooks across every scope, shows which events they target, and lets you verify your configuration is loaded correctly. Pair it with --debug "hooks" when troubleshooting execution order or matcher issues.

Event Matchers

Matchers are regex patterns that filter which specific instances of an event trigger your hook. Without a matcher, the hook fires for every occurrence of that event type.

{"matcher": "Bash"}                    // Exact tool name
{"matcher": "Edit|Write"}             // Multiple tools (regex OR)
{"matcher": "mcp__memory__.*"}        // All MCP memory server tools
{"matcher": "mcp__.*__write.*"}       // Any MCP write operation

Matchers are case-sensitive and use full regex syntax. This means Bash* does not mean “anything starting with Bash” — it means “Bas” followed by zero or more “h” characters. For exact tool matching, just use the tool name directly: Bash.

For Notification events, the matcher targets the notification type (permission_prompt, idle_prompt) rather than a tool name. For SessionStart, it matches the session source (startup, resume, clear, compact).

Exit Code Behavior

Command handlers communicate their decision through exit codes. The convention is specific to the hooks system and differs from typical Unix expectations.

What exit code 2 blocks depends on the event:

Hooks in the same event array run sequentially in array order. The first hook to exit with code 2 wins — subsequent hooks in the array are not executed.

Environment Variables

Command hooks automatically receive several environment variables:

• CLAUDE_PROJECT_DIR — project root directory
• CLAUDE_PLUGIN_ROOT — plugin installation directory
• CLAUDE_PLUGIN_DATA — plugin persistent data directory
• CLAUDE_ENV_FILE — (SessionStart only) file path for persisting environment variables across the session

The CLAUDE_ENV_FILE variable deserves special attention. In a SessionStart hook, you can write export statements to this file to set environment variables that persist for all subsequent Bash commands in the session:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi
exit 0