---

name: meta:hook-creator description: Create event hooks for Claude Code that trigger on specific events. Generate hooks with proper JSON configuration for automating workflows. Use when creating hooks, setting up event triggers, automating on file saves or tool calls.

Hook Creator

Quick Start

Add a hook to .claude/settings.json:

Copy{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'File written!'"
          }
        ]
      }
    ]
  }
}

Use /hooks command to manage hooks interactively.

Choosing an Approach

Decision Tree

CopyNeed to detect a pattern and warn/block?
  └─ Yes → Use hookify (/hookify "Don't use console.log")
  └─ No, need complex logic?
       └─ Yes → Use Python hook script
       └─ No, just a simple command?
            └─ Yes → Inline in settings.json

When to Use Hookify

• Block/warn based on regex pattern matching
• Quick setup without writing code
• Personal rules (.local.md files aren't committed)

Copy# .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.

When to Use Python Hooks

• Check file existence or conditions
• Run external validators
• Parse and analyze content
• Call APIs or external tools

Copy#!/usr/bin/env -S uv run --quiet --script
# .claude/hooks/schema-change.py
import json, sys

input_data = json.loads(sys.stdin.read())
file_path = input_data.get("tool_input", {}).get("file_path", "")

if "src/modules/db/schema" in file_path:
    print("📦 Schema modified. Run: pnpm db:generate")

Hook Locations

Event Types

Notification Matchers

SessionStart Matchers

Exit Codes

Hook Types

Command Hook

Executes a shell command:

Copy{
  "type": "command",
  "command": "your-shell-command",
  "timeout": 30
}

Prompt Hook (LLM-based)

Uses an LLM to evaluate (Stop/SubagentStop only):

Copy{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS",
  "timeout": 30
}

Environment Variables

Persist Environment (SessionStart)

Copy#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi

Matcher Patterns

Hook Configuration

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

Hooks in Components

Skills, agents, and commands can define hooks in frontmatter:

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

Supported events: PreToolUse, PostToolUse, Stop

The once: true option runs the hook only once per session (skills/commands only).

Common Templates

Block Dangerous Commands

Copy{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'input=$(cat); if echo \"$input\" | jq -e \".tool_input.command | test(\\\"rm -rf|--force\\\"; \\\"i\\\")\" >/dev/null 2>&1; then echo \"Blocked: Dangerous command\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

Protect Files

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

Auto-Format TypeScript

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

Desktop Notification

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

Script-Based Hooks

For complex logic, use Python scripts with uv instead of inline bash. See reference.md for templates and examples.

Common Mistakes

Validation

Run validation after every hook change:

Copyuv run .claude/skills/meta-hook-creator/scripts/validate-hook.py .claude/settings.json

Checklist

• Hook defined in settings.json
• Event type is valid
• Matcher pattern correct for event
• Command handles stdin JSON properly
• Exit codes match intended behavior
• Timeout set appropriately
• External scripts are executable

Delegation

• After creating/modifying hooks: Run uv run .claude/skills/meta-hook-creator/scripts/validate-hook.py .claude/settings.json
• Pattern discovery: For existing hook patterns, use Explore agent

Additional Resources

• For advanced JSON output, MCP integration, security: reference.md
• For complete Python hook examples: examples.md

References

• Official Hooks Reference: code.claude.com/docs/en/hooks
• Hooks Guide: code.claude.com/docs/en/hooks-guide
• jq Manual: stedolan.github.io/jq/manual