Hooks Configuration

Claude Code Hooks Configuration

Expert knowledge for configuring and developing Claude Code hooks to automate workflows and enforce best practices.

When to Use This Skill

Core Concepts

What Are Hooks? Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. Unlike relying on Claude to "decide" to run something, hooks provide deterministic, guaranteed execution.

Why Use Hooks?

• Enforce code formatting automatically
• Block dangerous commands before execution
• Inject context at session start
• Log commands for audit trails
• Send notifications when tasks complete

Hook Lifecycle Events

Stop vs SubagentStop: Stop fires at the session level when the main agent finishes a response turn. SubagentStop fires when an individual subagent (spawned via the Task tool) completes. Use Stop for session-level notifications; use SubagentStop for per-task quality gates.

For full schemas, examples, and timeout recommendations for each event, see .claude/rules/hooks-reference.md.

Configuration

File Locations

Hooks are configured in settings files:

• `~/.claude/settings.json` - User-level (applies everywhere)
• `.claude/settings.json` - Project-level (committed to repo)
• `.claude/settings.local.json` - Local project (not committed)

Claude Code merges all matching hooks from all files.

Frontmatter Hooks (Skills and Commands)

Hooks can also be defined directly in skill and command frontmatter using the hooks field:

---
name: my-skill
description: A skill with hooks
allowed-tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Pre-tool hook from skill'"
          timeout: 10
---

Basic Structure

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

Matcher Patterns

• Exact match: "Bash" - matches exactly "Bash" tool
• Regex patterns: "Edit|Write" - matches either tool
• Wildcards: "Notebook.*" - matches tools starting with "Notebook"
• All tools: "*" - matches everything
• MCP tools: "mcp__server__tool" - targets MCP server tools

Input/Output Schema Summary

Hooks receive JSON via stdin with common fields (session_id, transcript_path, cwd, permission_mode, hook_event_name). Event-specific fields include tool_name and tool_input for PreToolUse, plus tool_response for PostToolUse, and subagent_type/subagent_prompt for SubagentStart.

Exit codes: 0 = allow, 2 = block (stderr shown to Claude), other = non-blocking error.

JSON responses vary by event: PreToolUse uses hookSpecificOutput with permissionDecision; Stop/SubagentStop use decision/reason; SubagentStart uses updatedPrompt; SessionStart uses hookSpecificOutput with additionalContext.

For detailed hook schemas and examples, see REFERENCE.md.

Common Hook Patterns

Block Dangerous Commands (PreToolUse)

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block rm -rf /
if echo "$COMMAND" | grep -Eq 'rm\s+(-rf|-fr)\s+/'; then
    echo "BLOCKED: Refusing to run destructive command on root" >&2
    exit 2
fi

exit 0

Auto-Format After Edits (PostToolUse)

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *.py ]]; then
    ruff format "$FILE" 2>/dev/null
    ruff check --fix "$FILE" 2>/dev/null
elif [[ "$FILE" == *.ts ]] || [[ "$FILE" == *.tsx ]]; then
    prettier --write "$FILE" 2>/dev/null
fi

exit 0

Remind About Built-in Tools (PreToolUse)

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -Eq '^\s*cat\s+[^|><]'; then
    echo "REMINDER: Use the Read tool instead of 'cat'" >&2
    exit 2
fi

exit 0

Load Context at Session Start (SessionStart)

#!/bin/bash
GIT_STATUS=$(git status --short 2>/dev/null | head -5)
BRANCH=$(git branch --show-current 2>/dev/null)

CONTEXT="Current branch: $BRANCH\nPending changes:\n$GIT_STATUS"
jq -n --arg ctx "$CONTEXT" '{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": $ctx
  }
}'

For additional patterns (subagent injection, desktop notifications, audit logging, auto-approve, worktree setup, task gating), see REFERENCE.md.

Prompt-Based and Agent-Based Hooks

Four hook types: command (shell script, exit code), http (HTTPS endpoint), prompt (single-turn LLM call), and agent (multi-turn with tool access). Use command for deterministic rules; prompt/agent for judgment-based decisions. Add async: true for fire-and-forget; once: true to run only once per session.

Prompt and agent hooks work on PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, SubagentStop, TaskCompleted, UserPromptSubmit. All other events support command hooks only.

For hook type details, CLAUDE_ENV_FILE, and configuration examples, see REFERENCE.md and .claude/rules/prompt-agent-hooks.md.

Handling Blocked Commands

When a PreToolUse hook blocks a command:

Critical: User permission does NOT bypass hooks. Retrying a blocked command will fail again.

When command is legitimately needed:

1. Explain why the command is required 2. Describe alternatives considered and why they won't work 3. Provide exact command for user to run manually 4. Let user decide

Timeout Guidelines

The default hook timeout is 600s (10 minutes) since Claude Code 2.1.50. Set explicit timeouts to document intent and prevent "Hook cancelled" errors:

Background Subshell Pattern (Recommended for Slow Hooks)

When a hook needs to do slow work (logging, API calls) without blocking, run it in a background subshell:

#!/bin/bash
# Exits instantly; slow work continues in background
(
  echo "$(date): Session ended" >> ~/.claude/session.log
  # Any other slow work...
) &>/dev/null &
exit 0

Why this works: ( ) creates a subshell, & runs it in background, &>/dev/null prevents stdout/stderr from blocking, exit 0 returns success immediately.

Best Practices

Debugging

Use /hooks to verify registration, claude --debug for verbose logging, and echo '{"tool_input":{"command":"..."}}' | bash your-hook.sh to test manually. Check $? for exit code. See hooks/README.md for plugin hook documentation.

Hooks Configuration Reference

Detailed schemas, configuration examples, and advanced hook patterns for Claude Code hooks.

Input Schema Details

Hooks receive JSON via stdin. All events include these common fields:

{
  "session_id": "unique-session-id",
  "transcript_path": "/path/to/conversation.json",
  "cwd": "/current/working/directory",
  "permission_mode": "mode",
  "hook_event_name": "PreToolUse"
}

PreToolUse Additional Fields

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

PostToolUse Additional Fields

{
  "tool_name": "Bash",
  "tool_input": { ... },
  "tool_response": { ... }
}

SubagentStart Additional Fields

{
  "subagent_type": "Explore",
  "subagent_prompt": "original prompt text",
  "subagent_model": "claude-opus"
}

Output Schema Details

Exit Codes

• 0: Success (command allowed)
• 2: Blocking error (stderr shown to Claude, operation blocked)
• Other: Non-blocking error (logged in verbose mode)

PreToolUse JSON Response

Wrapped in hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "explanation",
    "updatedInput": { "modified": "input" }
  }
}

Stop/SubagentStop JSON Response

{
  "decision": "block",
  "reason": "required explanation for continuing"
}

SubagentStart JSON Response (Input Modification)

{
  "updatedPrompt": "modified prompt text to inject context or modify behavior"
}

SessionStart JSON Response

Wrapped in hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Information to inject into session"
  }
}

PermissionRequest JSON Response

{"decision": "approve", "reason": "Read-only git operation"}
{"decision": "deny", "reason": "Destructive root operation blocked"}

Advanced Hook Patterns

Inject Context for Subagents (SubagentStart)

#!/bin/bash
INPUT=$(cat)
SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.subagent_type // empty')
ORIGINAL_PROMPT=$(echo "$INPUT" | jq -r '.subagent_prompt // empty')

# Add project context to Explore agents
if [ "$SUBAGENT_TYPE" = "Explore" ]; then
    PROJECT_INFO="Project uses TypeScript with Bun. Main source in src/."
    cat << EOF
{
  "updatedPrompt": "$PROJECT_INFO\n\n$ORIGINAL_PROMPT"
}
EOF
fi

exit 0

Desktop Notification on Stop (Stop)

#!/bin/bash
# Linux
notify-send "Claude Code" "Task completed" 2>/dev/null

# macOS
osascript -e 'display notification "Task completed" with title "Claude Code"' 2>/dev/null

exit 0

Audit Logging (PostToolUse)

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // "N/A"')

echo "$(date -Iseconds) | $TOOL | $COMMAND" >> ~/.claude/audit.log
exit 0

Auto-Approve Safe Operations (PermissionRequest)

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Auto-approve read-only git operations
if [ "$TOOL" = "Bash" ] && echo "$COMMAND" | grep -Eq '^git (status|log|diff|branch|remote)'; then
  echo '{"decision": "approve", "reason": "Read-only git operation"}'
  exit 0
fi

# Auto-deny destructive operations on root
if [ "$TOOL" = "Bash" ] && echo "$COMMAND" | grep -Eq 'rm\s+(-rf|-fr)\s+/'; then
  echo '{"decision": "deny", "reason": "Destructive root operation blocked"}'
  exit 0
fi

exit 0

Set Up Worktree Environment (WorktreeCreate)

#!/bin/bash
INPUT=$(cat)
WORKTREE_PATH=$(echo "$INPUT" | jq -r '.worktree_path')

if [ -f "$WORKTREE_PATH/package.json" ]; then
  (cd "$WORKTREE_PATH" && bun install --frozen-lockfile) 2>/dev/null
fi

exit 0

Gate Task Completion (TaskCompleted)

#!/bin/bash
INPUT=$(cat)
TASK_TITLE=$(echo "$INPUT" | jq -r '.task_title')

if echo "$TASK_TITLE" | grep -qi 'implement\|add\|fix\|refactor'; then
  if ! npm test --bail 2>/dev/null; then
    echo '{"decision": "block", "reason": "Tests must pass before task is accepted."}'
    exit 0
  fi
fi

exit 0

Configuration Examples

Anti-Pattern Detection

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash $CLAUDE_PROJECT_DIR/hooks-plugin/hooks/bash-antipatterns.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Auto-Format Python Files

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); [[ \"$FILE\" == *.py ]] && ruff format \"$FILE\"'"
          }
        ]
      }
    ]
  }
}

Git Reminder on Stop

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'changes=$(git status --porcelain | wc -l); [ $changes -gt 0 ] && echo \"Reminder: $changes uncommitted changes\"'"
          }
        ]
      }
    ]
  }
}

Prompt Hook Configuration

{
  "type": "prompt",
  "prompt": "Evaluate whether all tasks are complete. $ARGUMENTS",
  "model": "haiku",
  "timeout": 30,
  "statusMessage": "Checking completeness..."
}

Agent Hook Configuration

{
  "type": "agent",
  "prompt": "Check for TODO/FIXME comments and debugging artifacts in changed files. $ARGUMENTS",
  "model": "haiku",
  "timeout": 60,
  "statusMessage": "Checking implementation quality..."
}

HTTP Hook Configuration

{
  "type": "http",
  "url": "https://hooks.example.com/pre-tool-use",
  "headers": {
    "Authorization": "Bearer ${HOOKS_API_KEY}"
  },
  "timeout": 30
}

Only HTTPS URLs are allowed. Header values support ${ENV_VAR} expansion.

Prompt/Agent Hook Response Schema

Both prompt and agent hooks return the same response format:

{"ok": true}
{"ok": false, "reason": "Explanation of what's wrong"}

Stop Hook Loop Prevention

Stop hooks fire every time Claude finishes responding, including after acting on stop hook feedback. Include this check in Stop hook prompts:

First: if stop_hook_active is true in the input, respond with {"ok": true} immediately.

Prompt and Agent Hook Types

Additional handler fields:

• `async: true`: Fire-and-forget (non-blocking, exit code ignored)
• `once: true`: Run only once per session

Supported events for prompt/agent hooks: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, SubagentStop, TaskCompleted, UserPromptSubmit.

CLAUDE_ENV_FILE (SessionStart)

SessionStart hooks can write environment variables that persist for the session:

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo "NODE_ENV=development" >> "$CLAUDE_ENV_FILE"
fi

Prefer command hooks over agent hooks when logic is deterministic — eliminates LLM latency on every invocation.

Debugging

# Verify hook registration
/hooks

# Enable debug logging
claude --debug

# Test a hook manually
echo '{"tool_input": {"command": "cat file.txt"}}' | bash your-hook.sh
echo $?  # Check exit code