Hooks System

Intermediate

17 event-driven systems for building automation workflows

25 min read

What Are Hooks?

Hooks are deterministic code that automatically runs when specific events occur in Claude Code. Instead of relying on LLM judgment, they execute reliably according to predefined rules.

ℹ️Understanding Hooks easily

Hooks are "automatic reaction rules". They work similarly to smartphone automation apps (e.g., IFTTT).

For example:

"When Claude modifies a file → automatically format the code"
"When a session starts → show today's to-do list"
"When a dangerous command is about to run → block it"

Hooks are about setting up rules that say "When something happens → automatically do this".

Key Characteristics of Hooks

Deterministic: Operates on rules rather than LLM decisions, making behavior predictable
Automatic execution: Runs without user intervention when events occur
Extensible: Supports various handler types including shell commands, LLM prompts, and sub-agents
Safe control: Build safety mechanisms such as tool execution blocking, input validation, and auto-formatting

17 Events

Claude Code provides a total of 17 Hook events.

Event	When It Fires	Primary Use
SessionStart	When a session starts	Environment initialization, welcome message
UserPromptSubmit	After user prompt submission	Input validation, transformation
PreToolUse	Just before tool execution	Execution blocking, input modification
PostToolUse	Right after tool execution	Result processing, auto-formatting
PostToolUseFailure	After tool execution failure	Error handling, fallback execution
PermissionRequest	When permission is requested	Auto-approve/deny
Notification	When a notification occurs	Desktop notifications, logging
SubagentStart	When a sub-agent starts	Agent initialization
SubagentStop	When a sub-agent stops	Result collection, cleanup
Stop	When Claude's response is complete	Result validation, post-processing
TeammateIdle	When a teammate agent is idle	Task assignment
TaskCompleted	When a task is completed	Completion notification, post-processing
ConfigChange	When configuration changes	Config validation, synchronization
WorktreeCreate	When a worktree is created	Environment setup, dependency installation
WorktreeRemove	When a worktree is removed	Cleanup, temporary file deletion
PreCompact	Just before context compaction	Preserving important information
SessionEnd	When a session ends	Cleanup, logging, reporting

💡With 17 events, which ones should I use?

To start, knowing just these 3 is enough:

PostToolUse: The most commonly used. Use it to automatically run code formatting (prettier, eslint, etc.) after Claude modifies a file
SessionStart: Use it to automatically display project status when a session starts
PreToolUse: Use it to automatically block dangerous commands (e.g., file deletion)

You can learn the rest one at a time as the need arises.

3 Handler Types

Each Hook event can have 3 types of handlers attached to it.

ℹ️Which handler type should you choose?

A handler determines "what actually happens when an event fires."

Command: Runs a terminal command. (e.g., format code with prettier) → Most commonly used
Prompt: Asks the AI a simple question. (e.g., "Check if this task is complete")
Subagent: Runs an AI sub-agent. (e.g., "Perform a dedicated code review")

Starting with just the Command handler is sufficient.

Command Handler

The most common handler that executes shell commands. It receives JSON via stdin and outputs JSON via stdout.

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

Prompt Handler

Performs a single LLM call. Suitable for yes/no decisions or simple analysis.

{
  "hooks": {
    "Stop": [
      {
        "type": "prompt",
        "prompt": "Review whether the task just completed fully satisfies the original request. Respond 'no' if anything is missing, or 'yes' if it is complete."
      }
    ]
  }
}

When the Prompt handler returns "no", Claude performs additional work.

Agent Handler

Runs a sub-agent to perform complex validation. A maximum of 50 turns and a 60-second timeout apply.

{
  "hooks": {
    "Stop": [
      {
        "type": "agent",
        "prompt": "Run tests for all changed files, and fix any failing tests.",
        "tools": ["Bash(npm test)", "Read", "Edit"]
      }
    ]
  }
}

Hook Input JSON Format

Command handlers receive JSON data via stdin. The fields included vary depending on the event.

Common Fields

{
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "hook_event_name": "PreToolUse"
}

PreToolUse / PostToolUse Additional Fields

{
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/home/user/project/src/index.ts",
    "content": "..."
  }
}

UserPromptSubmit Additional Fields

{
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "The prompt content entered by the user"
}

Exit Codes

Claude Code's behavior changes depending on the Command handler's exit code.

Exit Code	Behavior
0	Proceed normally (if there is stdout output, it is passed to Claude)
2	Block the action (stop tool execution, deliver error message)
Other	Log a warning and proceed

Blocking Example

#!/bin/bash
# protect-files.sh - Block modification of protected files
 
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# Block .env file modifications
if [[ "$FILE_PATH" == *.env* ]]; then
  echo '{"error": "Cannot modify .env files."}'
  exit 2
fi
 
exit 0

Matchers

Use matchers to apply Hooks only to specific tools or patterns.

Matcher Types

Type	Description	Example
Exact string	Matches the tool name exactly	`"Write"`
Regex	Matches using a regex pattern	`"Write\|Edit"`
MCP tool	Matches MCP server tools	`"mcp__*"`

Matcher Usage Examples

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "/path/to/check-script.sh",
        "matcher": "Write|Edit"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write $CLAUDE_FILE_PATH",
        "matcher": "Write"
      },
      {
        "type": "command",
        "command": "/path/to/notify-mcp.sh",
        "matcher": "mcp__*"
      }
    ]
  }
}

If no matcher is specified, the Hook runs for all tool calls of that event.

Configuration Location

Hooks can be defined in 3 configuration files.

File	Scope	Git Tracked
`~/.claude/settings.json`	User global (all projects)	No
`.claude/settings.json`	Project (shared with team)	Yes
`.claude/settings.local.json`	Project local (personal)	No

Configuration File Example

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo 'Session has started.'"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "/path/to/guard.sh",
        "matcher": "Write|Edit"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write $CLAUDE_FILE_PATH",
        "matcher": "Write"
      }
    ],
    "Stop": [
      {
        "type": "prompt",
        "prompt": "Verify the task results."
      }
    ]
  }
}

Practical Pattern Examples

Pattern 1: Desktop Notifications (Notification)

Display desktop notifications when Claude completes a task or sends a notification.

{
  "hooks": {
    "Notification": [
      {
        "type": "command",
        "command": "notify-send 'Claude Code' \"$CLAUDE_NOTIFICATION\" --icon=terminal"
      }
    ]
  }
}

On macOS, use osascript.

{
  "hooks": {
    "Notification": [
      {
        "type": "command",
        "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
      }
    ]
  }
}

Pattern 2: Auto-Format (PostToolUse + Prettier)

Automatically run Prettier after writing or editing a file.

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

You can also apply ESLint auto-fix alongside it.

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

Pattern 3: Protected File Blocking (PreToolUse)

Block modifications to specific files or directories.

#!/bin/bash
# guard-protected-files.sh
 
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# Protected patterns
PROTECTED_PATTERNS=(
  "*.env"
  "*.env.*"
  "package-lock.json"
  "yarn.lock"
  "dist/*"
  "node_modules/*"
)
 
for PATTERN in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == $PATTERN ]]; then
    echo "{\"error\": \"Protected file: $FILE_PATH\"}"
    exit 2
  fi
done
 
exit 0

Connect this script in your settings.

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "/path/to/guard-protected-files.sh",
        "matcher": "Write|Edit"
      }
    ]
  }
}

Pattern 4: Context Re-injection (PreCompact)

Re-inject important information to prevent loss during context compaction.

{
  "hooks": {
    "PreCompact": [
      {
        "type": "command",
        "command": "echo '{\"inject\": \"Rules to always remember: 1) Use TypeScript strict mode 2) Write JSDoc comments for all functions 3) Maintain test coverage above 80%\"}'"
      }
    ]
  }
}

A script that automatically re-injects key content from CLAUDE.md is also useful.

#!/bin/bash
# reinject-context.sh
 
CLAUDE_MD="$CLAUDE_CWD/CLAUDE.md"
if [[ -f "$CLAUDE_MD" ]]; then
  CONTENT=$(cat "$CLAUDE_MD" | head -50)
  echo "{\"inject\": \"Project rules (CLAUDE.md): $CONTENT\"}"
fi
exit 0

Pattern 5: Task Completion Verification (Stop + prompt hook)

Automatically verify the quality of results when Claude finishes a response.

{
  "hooks": {
    "Stop": [
      {
        "type": "prompt",
        "prompt": "Review the task just completed. Check the following items: 1) Was the original request fully satisfied? 2) Is the newly written code free of obvious bugs? 3) Are there no TypeScript type errors? Respond 'no' if there are issues, or 'yes' if everything passes."
      }
    ]
  }
}

Using this pattern, Claude self-reviews its work and automatically addresses any shortcomings.

Pattern 6: Automatic Permission Handling (PermissionRequest)

Automatically handle repetitive permission approvals.

#!/bin/bash
# auto-permission.sh
 
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
# Auto-approve files inside the project
PROJECT_DIR="/home/user/my-project"
if [[ "$FILE_PATH" == "$PROJECT_DIR"* ]]; then
  echo '{"decision": "allow"}'
  exit 0
fi
 
# Block files outside the project
echo '{"decision": "deny", "reason": "Access to files outside the project has been blocked."}'
exit 0

{
  "hooks": {
    "PermissionRequest": [
      {
        "type": "command",
        "command": "/path/to/auto-permission.sh"
      }
    ]
  }
}

Hook Debugging Tips

Adding Logging

Record the Hook execution process to a log file to diagnose issues.

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "cat | tee -a /tmp/claude-hooks.log | /path/to/hook-script.sh"
      }
    ]
  }
}

Step-by-Step Testing

When creating a new Hook, start with a simple echo to verify that the event fires correctly.

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "echo 'Test Hook executed' >> /tmp/hook-test.log"
      }
    ]
  }
}

Cautions

Make sure Hook scripts have execute permissions (chmod +x)
Watch out for infinite loops (where a Hook calls a tool, and that tool triggers the Hook again)
Timeout: Command handlers have a default 60-second timeout
Error handling: Errors with exit codes other than 2 only log a warning and proceed, so use exit 2 when you must block an action

Was this helpful?

Related:Sub-Agents Agent Teams