Hooks

Hooks are automated scripts that execute in response to specific events during Claude Code sessions. They enable automation, validation, permission management, and custom workflows.

Overview

Hooks are automated actions (shell commands, HTTP webhooks, LLM prompts, MCP tool calls, or subagent evaluations) that execute automatically when specific events occur in Claude Code. They receive JSON input and communicate results via exit codes and JSON output.

Key features:

• Event-driven automation
• JSON-based input/output
• Support for command, http, mcp_tool, prompt, and agent hook types
• Pattern matching for tool-specific hooks

Configuration

Hooks are configured in settings files with a specific structure:

• ~/.claude/settings.json - User settings (all projects)
• .claude/settings.json - Project settings (shareable, committed)
• .claude/settings.local.json - Local project settings (not committed)
• Managed policy - Organization-wide settings
• Plugin hooks/hooks.json - Plugin-scoped hooks
• Skill/Agent frontmatter - Component lifetime hooks

Basic Configuration Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Key fields: