Claude Code Research

Hooks Quick Start

4 min read

Claude Code Hooks Quick Start

Claude Code hooks are user-defined shell commands that execute automatically at specific points during Claude Code’s operation, providing deterministic control over behavior.

What are Hooks?

Hooks allow you to:

  • Auto-format code after edits (prettier, black, etc.)
  • Validate changes before they’re applied
  • Send notifications when tasks complete
  • Enforce security policies on file operations
  • Integrate with external tools (linters, tests, etc.)

Quick Start

1. Create Configuration File

Create .claude/settings.json in your project:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

2. Test Your Hooks

# View current hooks configuration
/hooks
 
# Ask Claude to edit a file to see hooks in action

3. Common Hook Patterns

Auto-formatting

{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "command": "prettier --write $CLAUDE_FILE_PATHS"
    }]
  }]
}

Security Check

{
  "PreToolUse": [{
    "matcher": ".*",
    "hooks": [{
      "command": "[[ \"$CLAUDE_FILE_PATHS\" =~ \\.env ]] && exit 2 || exit 0"
    }]
  }]
}

Task Notifications

{
  "Stop": [{
    "hooks": [{
      "command": "notify-send 'Claude Code' 'Task completed'"
    }]
  }]
}

Key Concepts

Hook Events

  • PreToolUse: Before tool execution (can block with exit code 2)
  • PostToolUse: After successful tool execution
  • Stop: When main agent finishes
  • UserPromptSubmit: When user submits a prompt

Environment Variables

  • $CLAUDE_TOOL_NAME - The tool being used (Edit, Write, etc.)
  • $CLAUDE_FILE_PATHS - Files being modified
  • $CLAUDE_TOOL_INPUT - Tool input as JSON

Exit Codes

  • 0 - Success, continue normally
  • 2 - Block operation (PreToolUse only)
  • Other - Warning, but continue

Hook Execution Lifecycle

Understanding the hook lifecycle is crucial for debugging and creating custom hooks. The process follows a clear sequence from registration to execution.

graph TD
    A[1. Hook Registration] --> B{2. Event Trigger};
    B --> C[3. Hook Queue Processing];
    C --> D{4. Middleware Execution};
    D --> E[5. Data Transformation];
    E --> F[6. Final Output];

Execution Steps:

  1. Registration: Hooks are registered with the HookManager during application startup. The system reads .claude/settings.json and validates all hook configurations. See Hook Design Patterns for examples.

  2. Event Trigger: An event occurs during Claude Code’s operation:

    • A tool like Edit or Write is about to execute (PreToolUse)
    • A tool has completed successfully (PostToolUse)
    • The main agent completes its task (Stop)
    • User submits a new prompt (UserPromptSubmit)

  3. Queue Processing: The HookManager gathers all registered hooks for the triggered event:

    • Filters hooks by their matcher patterns
    • Sorts hooks by priority (if specified)
    • Prepares the execution environment with variables

  4. Middleware Execution: Hooks execute sequentially:

    • Each hook runs as a separate shell process
    • Exit codes determine flow control
    • Output is captured for debugging

  5. Data Transformation: Hook outputs can modify Claude Code’s behavior:

    • PreToolUse hooks can block operations (exit code 2)
    • PostToolUse hooks can trigger additional actions
    • Environment variables pass data between hooks

  6. Final Output: The hook chain completes and Claude Code continues:

    • Success: Normal operation proceeds
    • Blocked: Operation is cancelled (PreToolUse only)
    • Warning: Operation continues with logged warnings

Debugging Hook Execution

To trace hook execution, use the /hooks command to see your current configuration, or check the Claude Code logs for detailed execution traces. Each hook execution includes timing information and exit codes.

Example Flow: When you edit a TypeScript file:

  1. Claude Code triggers PreToolUse event
  2. Security hook checks file permissions → Exit 0 (continue)
  3. Edit operation executes
  4. Claude Code triggers PostToolUse event
  5. Prettier formats the file → Exit 0 (success)
  6. ESLint checks for issues → Exit 0 (success)
  7. File is saved with all transformations applied

Complete Reference

For detailed configuration options, all hook events, advanced patterns, and troubleshooting:

📖 Complete Configuration Reference

Next Steps

Graph View

Backlinks