Meta Hook Creator

Hook Creator

Overview

Claude Code hooks are user-defined shell commands, LLM prompts, or agent evaluations that execute automatically at specific lifecycle points. Hooks receive JSON context via stdin, take action, and communicate results through exit codes, stdout, and stderr.

When to use: Blocking dangerous commands, auto-formatting after writes, protecting sensitive files, custom notifications, environment setup, enforcing project conventions, auto-approving safe tools, running tests after changes.

When NOT to use: Static context injection (use CLAUDE.md), simple permission rules (use allowlist settings), one-time setup (use shell scripts directly).

Quick Reference

Common Mistakes

Delegation

• Hook pattern discovery: Use Explore agent to find existing hooks in the project
• Hook testing and verification: Use Task agent to validate hook behavior
• Code review: Delegate to code-reviewer agent for hook script review

References

• Event types, matchers, and input schemas
• Hook configuration, exit codes, JSON output, and environment variables
• Hook templates for common automation patterns

Event Types

Lifecycle Overview

Events fire in this order during a session:

1. SessionStart -- session begins or resumes 2. UserPromptSubmit -- user sends a prompt 3. PreToolUse -- before each tool call (can block) 4. PermissionRequest -- when permission dialog would appear (can auto-approve/deny) 5. PostToolUse -- after tool succeeds 6. PostToolUseFailure -- after tool fails 7. SubagentStart -- when a subagent spawns 8. SubagentStop -- when a subagent finishes (can force continue) 9. Notification -- when Claude Code sends a notification 10. Stop -- when Claude finishes responding (can force continue) 11. PreCompact -- before context compaction 12. SessionEnd -- session terminates

SessionStart

Fires when a session begins or resumes. Use for environment setup and loading context.

Matcher values: startup, resume, clear, compact

Input fields (in addition to common fields):

Decision control: stdout text or additionalContext is added to Claude's context.

Special: CLAUDE_ENV_FILE env var is available only in this event. Write export statements to persist environment variables for the session.

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

UserPromptSubmit

Fires when the user submits a prompt, before Claude processes it. Use for validation or adding context.

Matcher: Not supported. Always fires on every prompt.

Input fields:

Decision control:

Plain text stdout on exit 0 is also added as context.

PreToolUse

Fires before a tool call executes. Use for validation, blocking, modifying inputs, or auto-approving.

Matcher: Tool name. Values include Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch, and MCP tools (mcp__<server>__<tool>).

Input fields:

Tool input schemas by tool:

// Bash
{ "command": "npm test", "description": "Run tests", "timeout": 120000 }

// Write
{ "file_path": "/path/to/file.txt", "content": "file content" }

// Edit
{ "file_path": "/path/to/file.txt", "old_string": "original", "new_string": "replacement" }

// Read
{ "file_path": "/path/to/file.txt", "offset": 10, "limit": 50 }

// Glob
{ "pattern": "**/*.ts", "path": "/path/to/dir" }

// Grep
{ "pattern": "TODO.*fix", "path": "/path/to/dir", "glob": "*.ts" }

Decision control (via hookSpecificOutput):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

PermissionRequest

Fires when a permission dialog is about to appear. Use for auto-approving or denying.

Matcher: Tool name, same values as PreToolUse.

Input fields: Same as PreToolUse but without tool_use_id. Includes permission_suggestions array with the "always allow" options.

Decision control (via hookSpecificOutput.decision):

PostToolUse

Fires after a tool completes successfully. Use for formatting, logging, or feedback.

Matcher: Tool name, same values as PreToolUse.

Input fields:

Decision control:

PostToolUseFailure

Fires when a tool execution fails. Use for logging, alerts, or corrective feedback.

Matcher: Tool name, same values as PreToolUse.

Input fields: Same as PostToolUse but with error info instead of tool_response:

Decision control: additionalContext only.

Notification

Fires when Claude Code sends a notification.

Matcher values: permission_prompt, idle_prompt, auth_success, elicitation_dialog

Input fields:

Decision control: Cannot block notifications. additionalContext adds context to the conversation.

SubagentStart

Fires when a subagent spawns via the Task tool.

Matcher values: Agent type -- Bash, Explore, Plan, or custom agent names.

Input fields:

Decision control: Cannot block creation. additionalContext is injected into the subagent's context.

SubagentStop

Fires when a subagent finishes. Uses same decision control as Stop.

Matcher values: Same as SubagentStart.

Input fields:

Stop

Fires when the main agent finishes responding. Does not fire on user interrupt.

Matcher: Not supported. Always fires.

Input fields:

Decision control:

Always check stop_hook_active to prevent infinite loops.

PreCompact

Fires before context compaction.

Matcher values: manual, auto

Input fields:

SessionEnd

Fires when a session terminates. Use for cleanup and logging.

Matcher values: clear, logout, prompt_input_exit, bypass_permissions_disabled, other

Input fields:

Cannot block session termination.

Matcher Patterns

Common Input Fields

All events receive these fields via stdin JSON:

Hook Configuration

Choosing an Approach

Hookify Example

Pattern-based rules without code. Personal rules use .local.md suffix and aren't committed:

# .claude/hookify.warn-console-log.local.md

---

name: warn-console-log
enabled: true
event: file
pattern: console\.log\(
action: warn

---

Remove console.log before committing.

See the hookify skill for full hookify documentation.

Settings Locations

Hooks are snapshotted at startup. Mid-session changes require review in the /hooks menu before taking effect.

Configuration Structure

Three levels of nesting: event, matcher group, hook handlers.

{
  "hooks": {
    "<EventType>": [
      {
        "matcher": "<regex-pattern>",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/script.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Multiple matcher groups per event and multiple hooks per matcher are supported. All matching hooks run in parallel. Identical handlers are deduplicated automatically.

Hook Types

Command Hooks

Execute a shell command. Receives JSON input on stdin, communicates via exit codes and stdout.

Prompt Hooks

Send a prompt to an LLM for single-turn evaluation. Returns a yes/no JSON decision.

Supported events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop.

Response schema:

{
  "ok": true,
  "reason": "Explanation (required when ok is false)"
}

Agent Hooks

Spawn a subagent with tool access (Read, Grep, Glob) for multi-turn verification.

Same supported events and response schema as prompt hooks. Up to 50 turns.

Exit Codes

Exit 2 behavior per event:

JSON Output

Print JSON to stdout on exit 0 for structured control. JSON is ignored on non-zero exit.

Top-level fields (all events):

Event-specific fields go in hookSpecificOutput with a hookEventName field:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Not allowed in production"
  }
}

Choose one approach per hook: exit codes alone, or exit 0 with JSON. Do not mix.

Environment Variables

Standard shell environment variables are also available.

Async Hooks

Set "async": true on command hooks to run in the background. Claude continues immediately.

• Only type: "command" supports async
• Cannot return decisions (action already proceeded)
• Output delivered on next conversation turn via systemMessage or additionalContext
• Each firing creates a separate background process (no deduplication)
• Default timeout same as sync hooks (600s)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests.sh",
            "async": true,
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Hooks in Skills and Agents

Skills and agents can define hooks in YAML frontmatter. These hooks are scoped to the component's lifecycle and cleaned up when it finishes.

---
name: secure-operations
hooks:
  PreToolUse:
    - matcher: 'Bash'
      hooks:
        - type: command
          command: './scripts/security-check.sh'
          once: true
---

All hook events are supported. For subagents, Stop hooks are automatically converted to SubagentStop. The once: true option runs the hook only once per session (skills only).

The /hooks Menu

Type /hooks in Claude Code to view, add, and delete hooks interactively. Hook source labels:

Disabling Hooks

• Remove the hook entry from settings JSON, or delete via /hooks menu
• Set "disableAllHooks": true in settings to temporarily disable all hooks
• No way to disable individual hooks while keeping them in config

Hook Execution Details

Plugin Hooks

Plugins define hooks in hooks/hooks.json within the plugin directory. Use $CLAUDE_PLUGIN_ROOT for paths relative to the plugin.

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Plugin hooks run alongside user/project hooks in parallel. They use the [Plugin] label in the /hooks menu.

Security Considerations

1. Validate inputs — never trust stdin data blindly; use try/except or jq -r '... // empty' 2. Quote shell variables — use "$VAR" not $VAR to prevent word splitting 3. Block path traversal — check for .. in file paths before processing 4. Use absolute paths — reference scripts with "$CLAUDE_PROJECT_DIR"/.claude/hooks/script.sh 5. Skip sensitive files — avoid processing .env, .git/, credential files 6. Hooks are snapshotted — external modifications require /hooks review before taking effect 7. Changes don't affect current session — a hook change mid-session only loads after explicit reload

Debugging

Enable Debug Mode

claude --debug

Debug output shows hook matching and execution:

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Hook command completed with status 0

Toggle verbose mode during a session with Ctrl+O.

Test Hook Manually

Pipe sample JSON to the hook script to verify behavior outside Claude:

echo '{"tool_input":{"file_path":"test.ts"}}' | .claude/hooks/my-hook.sh
echo $?

Log Hook Execution

Wrap a hook command to capture input for debugging:

{
  "type": "command",
  "command": "bash -c 'input=$(cat); echo \"$input\" >> ~/.claude/hook-debug.log; echo \"$input\" | .claude/hooks/actual-hook.sh'"
}

jq Quick Reference

Common patterns for extracting fields from hook stdin JSON:

# Extract file path
jq -r '.tool_input.file_path // empty'

# Extract command
jq -r '.tool_input.command // empty'

# Check pattern match (exit 0 if match, 1 if not)
jq -e '.tool_input.command | test("pattern")'

# Safe extraction with fallback
jq -r '.field // "default"' 2>/dev/null

Hook Templates

Block Dangerous Commands

Block shell commands matching a pattern. Uses exit 2 to prevent the tool call.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'COMMAND=$(jq -r \".tool_input.command\"); if echo \"$COMMAND\" | grep -q \"rm -rf\"; then echo \"Blocked: destructive command\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

Script-based version with JSON decision output:

#!/bin/bash
# .claude/hooks/block-dangerous.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo '{"decision":"block","reason":"Destructive command blocked by hook"}'
else
  exit 0
fi

Protect Files from Modification

Block writes to sensitive files like .env, lock files, or config.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'PATH_VAL=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$PATH_VAL\" == *.env* ]] || [[ \"$PATH_VAL\" == *lock* ]]; then echo \"Blocked: protected file\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

Auto-Format After Write

Run a formatter after Claude writes or edits TypeScript files.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.ts ]] || [[ \"$FILE\" == *.tsx ]]; then npx prettier --write \"$FILE\" 2>/dev/null; fi'",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Desktop Notification on Permission Request

Send a macOS notification when Claude needs permission approval.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs permission\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

For Linux, use notify-send:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude needs permission'"
          }
        ]
      }
    ]
  }
}

Auto-Approve Safe Commands

Automatically approve specific safe commands without prompting.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'CMD=$(jq -r \".tool_input.command\"); if [[ \"$CMD\" == npm\\ test* ]] || [[ \"$CMD\" == npx\\ prettier* ]]; then echo \"{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PreToolUse\\\",\\\"permissionDecision\\\":\\\"allow\\\",\\\"permissionDecisionReason\\\":\\\"Safe command auto-approved\\\"}}\"; fi'"
          }
        ]
      }
    ]
  }
}

Environment Setup on Session Start

Set environment variables that persist for all Bash commands in the session.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [ -n \"$CLAUDE_ENV_FILE\" ]; then echo \"export NODE_ENV=development\" >> \"$CLAUDE_ENV_FILE\"; echo \"export PATH=\\\"\\$PATH:./node_modules/.bin\\\"\" >> \"$CLAUDE_ENV_FILE\"; fi'"
          }
        ]
      }
    ]
  }
}

Script-based version that captures environment from a setup command:

#!/bin/bash
# .claude/hooks/setup-env.sh
ENV_BEFORE=$(export -p | sort)

source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

Force Continue Until Tests Pass (Prompt Hook)

Use an LLM-based hook to evaluate whether Claude should stop.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete and no errors remain. Respond with {\"ok\": true} to allow stopping or {\"ok\": false, \"reason\": \"explanation\"} to continue.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Run Tests After File Changes (Async)

Run tests in the background without blocking Claude. Results are delivered on the next turn.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/run-tests-async.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"
else
  echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"
fi

Python Hooks

For complex logic, use Python with uv for dependency management. Python hooks are more readable and maintainable than inline bash for multi-step logic.

Python Hook Template

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
"""Hook description."""

import json
import sys

def main() -> int:
    input_data = json.loads(sys.stdin.read())

    # Extract relevant fields
    tool_input = input_data.get("tool_input", {})
    file_path = tool_input.get("file_path", "")
    content = tool_input.get("content", "")

    # Your logic here

    # Exit codes: 0=success, 1=error, 2=block (PreToolUse only)
    return 0

if __name__ == "__main__":
    sys.exit(main())

PreToolUse Validator

Block dangerous commands before execution using regex patterns:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
import json
import re
import sys

BLOCKED_PATTERNS = [
    (r"\brm\s+-rf\b", "Blocked: rm -rf is dangerous"),
    (r"--force\b", "Blocked: --force operations disabled"),
]

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(1)

command = data.get("tool_input", {}).get("command", "")

for pattern, message in BLOCKED_PATTERNS:
    if re.search(pattern, command, re.I):
        print(message, file=sys.stderr)
        sys.exit(2)

sys.exit(0)

UserPromptSubmit with Context

Add context to every user prompt:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
import json
import sys
import datetime

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(1)

# Add context to conversation
context = f"Current time: {datetime.datetime.now()}"
print(context)

sys.exit(0)

Auto-Approve Documentation Files

Automatically approve read access to documentation without prompting:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
import json
import sys

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(1)

tool_name = data.get("tool_name", "")
file_path = data.get("tool_input", {}).get("file_path", "")

if tool_name == "Read" and file_path.endswith((".md", ".txt", ".json")):
    output = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "allow",
            "permissionDecisionReason": "Documentation auto-approved"
        },
        "suppressOutput": True
    }
    print(json.dumps(output))

sys.exit(0)

Schema Change Notification

Notify when database schema files are modified:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
import json
import sys

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(1)

file_path = data.get("tool_input", {}).get("file_path", "")

if "schema" in file_path and file_path.endswith(".ts"):
    print("Schema modified. Remember to run: pnpm db:generate")

sys.exit(0)

Protected File Blocker

Block modifications to sensitive files:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
import json
import sys

PROTECTED_PATTERNS = [
    ".env",
    ".env.local",
    "credentials",
    "secrets",
    ".git/",
]

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(1)

file_path = data.get("tool_input", {}).get("file_path", "")

for pattern in PROTECTED_PATTERNS:
    if pattern in file_path:
        print(f"Blocked: Cannot modify protected file ({pattern})", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

Post-Write Formatter

Format files automatically after writing based on file type:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# ///
import json
import subprocess
import sys
from pathlib import Path

try:
    data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(1)

file_path = data.get("tool_input", {}).get("file_path", "")

if not file_path or not Path(file_path).exists():
    sys.exit(0)

if file_path.endswith((".ts", ".tsx", ".js", ".jsx")):
    subprocess.run(["npx", "prettier", "--write", file_path], capture_output=True)
elif file_path.endswith(".py"):
    subprocess.run(["ruff", "format", file_path], capture_output=True)
elif file_path.endswith(".md"):
    subprocess.run(["npx", "markdownlint", "--fix", file_path], capture_output=True)

sys.exit(0)