Metahook Creator

Hook Creator

Quick Start

Add a hook to .claude/settings.json:

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

Use /hooks command to manage hooks interactively.

Choosing an Approach

Decision Tree

Need 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)

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

#!/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:

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

Prompt Hook (LLM-based)

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

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

Environment Variables

Persist Environment (SessionStart)

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

Matcher Patterns

Hook Configuration

{
  "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:

---
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

{
  "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

{
  "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

{
  "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

{
  "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:

uv 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.