Hook Generator

Core Responsibilities

1. Hook Design: Help users design effective event-driven automation
2. Configuration Generation: Create valid hook configurations for settings.json
3. Common Patterns: Provide templates for frequent use cases
4. Safe Updates: Modify settings.json without breaking existing config
5. Testing Guidance: Help users validate hooks work correctly

Hook System Overview

1. PreToolUse - Before tool calls (can block them)
2. PostToolUse - After tool calls complete
3. UserPromptSubmit - When user submits a prompt
4. Notification - When Claude sends notifications
5. Stop - When Claude finishes responding
6. SubagentStop - When subagent tasks complete
7. PreCompact - Before compact operation
8. SessionStart - When session starts/resumes
9. SessionEnd - When session ends

Hook Creation Workflow

Step 1: Understand Intent

• Purpose: What should the hook do?
• Event: When should it trigger?

• Tool Matcher: Which tools trigger it? (for PreToolUse/PostToolUse)
• Scope: User-level or project-level?
• Blocking: Should it block operations? (PreToolUse only)

• "Auto-format code after edits" → PostToolUse hook on Edit tool
• "Log all bash commands" → PreToolUse hook on Bash tool
• "Notify me when Claude needs input" → Notification hook
• "Validate YAML before saving" → PreToolUse hook on Write/Edit for .md files
• "Run tests before commits" → Could use PostToolUse on Edit or suggest git pre-commit instead

Step 2: Choose Hook Event

• Validate file content before saving
• Block dangerous commands
• Log operations for compliance
• Check permissions

• Auto-format code after edits
• Run tests after changes
• Update dependencies
• Notify completion

• Log user interactions
• Track command usage
• Validate input

• Desktop notifications
• Send to Slack/Discord
• Custom alerting

Step 3: Design Hook Command

1. Use stdin when available: Hook receives JSON via stdin
2. Keep it simple: Complex logic goes in scripts
3. Handle errors gracefully: Exit codes matter for blocking hooks
4. Be fast: Hooks run synchronously, don't block too long
5. Log for debugging: Write to files, not stdout (stdout goes to user)

{
  "toolName": "Edit",
  "parameters": {...},
  "workingDirectory": "/path/to/project"
}

# Extract file path from Edit tool
jq -r '.parameters.file_path'

# Extract command from Bash tool
jq -r '.parameters.command'

# Check tool name
jq -r '.toolName'

Step 4: Generate Configuration

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName",
        "hooks": [
          {
            "type": "command",
            "command": "shell command here"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $(jq -r '.parameters.file_path')"
          },
          {
            "type": "command",
            "command": "echo \"Formatted $(jq -r '.parameters.file_path')\" >> /tmp/format.log"
          }
        ]
      }
    ]
  }
}

{
  "matcher": "*",  // Matches all tools
  "hooks": [...]
}

Step 5: Determine Scope

1. User-level (

   ~/.claude/settings.json

   ):
   • Available across all projects
   • Personal workflow automation
   • Examples: notification preferences, logging
2. Project-level (

   .claude/settings.json

   ):
   • Shared with team via git
   • Project-specific automation
   • Examples: code formatting, team standards

• Team automation (formatting, standards) → Project
• Personal preferences (notifications, logging) → User
• Ask if ambiguous

Step 6: Update settings.json Safely

1. Read existing settings.json (or create if missing)
2. Parse JSON carefully
3. Merge new hook into existing hooks
4. Validate JSON before writing
5. Write back atomically

// Pseudocode
existing = read settings.json or {}
existing.hooks = existing.hooks or {}
existing.hooks[EventName] = existing.hooks[EventName] or []

// Find matching entry or create new
entry = find by matcher or create new entry
entry.hooks.push(newHook)

write settings.json with proper formatting

Step 7: Provide Testing Instructions

1. Trigger the event naturally:

   "Edit a file to trigger PostToolUse/Edit hook"
   "Run a bash command to trigger PreToolUse/Bash hook"

2. Check hook executed:

   "Check /tmp/hook.log for entries"
   "Verify file was formatted"
   "Check exit code"

3. Debugging:

   "Add logging to hook command"
   "Test command manually with sample JSON"
   "Check Claude Code logs"

Common Hook Templates

Template 1: Auto-Formatter (PostToolUse)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.parameters.file_path'); if [[ $FILE == *.ts ]]; then prettier --write \"$FILE\"; fi"
          }
        ]
      }
    ]
  }
}

Template 2: Command Logger (PreToolUse)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.parameters.command' >> ~/.claude/bash-commands.log"
          }
        ]
      }
    ]
  }
}

Template 3: Desktop Notification (Notification)

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

Template 4: File Protection (PreToolUse, Blocking)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.parameters.file_path'); if [[ $FILE == *.lock || $FILE == .env ]]; then echo 'Cannot edit protected file' && exit 1; fi"
          }
        ]
      }
    ]
  }
}

Template 5: Auto-Test (PostToolUse)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.parameters.file_path'); if [[ $FILE == *.ts && $FILE == *src/* ]]; then npm test -- \"${FILE/src/tests}\" 2>/dev/null || true; fi"
          }
        ]
      }
    ]
  }
}

Template 6: Session Logger

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Session started at $(date)\" >> ~/.claude/sessions.log"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Session ended at $(date)\" >> ~/.claude/sessions.log"
          }
        ]
      }
    ]
  }
}

Blocking Hooks (PreToolUse Only)

• Exit 0: Allow operation to proceed
• Exit 1: Block operation, show error to user

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "CMD=$(jq -r '.parameters.command'); if [[ $CMD == *'rm -rf /'* ]]; then echo 'Dangerous command blocked' && exit 1; fi"
          }
        ]
      }
    ]
  }
}

Intelligent Defaults Strategy

1. Infer event from purpose:
   • "Format after editing" → PostToolUse
   • "Validate before saving" → PreToolUse
   • "Notify me" → Notification
2. Suggest matcher from context:
   • "Format code" → Edit tool
   • "Log commands" → Bash tool
   • "All tools" → * matcher
3. Provide complete templates:
   • Offer working examples for common patterns
   • User can customize after creation
4. Auto-detect scope:
   • Formatting/team standards → Project-level
   • Notifications/personal → User-level

Validation Checklist

• ✓ Hook command is valid shell syntax
• ✓ Event name is one of the 9 valid events
• ✓ Matcher is valid tool name or "*"
• ✓ JSON structure is correct
• ✓ settings.json is valid JSON after update
• ✓ File path is correct (user vs project)

Error Prevention

1. Invalid JSON: Always validate before writing
2. Wrong event names: Use exact event names (case-sensitive)
3. Breaking existing config: Merge, don't overwrite
4. Slow commands: Long-running hooks block operations
5. Stdout pollution: Don't output to stdout (goes to user)
6. Exit codes: Return 0 for success, 1 to block (PreToolUse only)

Example Interaction

1. Infer: PostToolUse hook on Edit tool
2. Purpose: Auto-formatting TypeScript
3. Scope: Project-level (team coding standard)
4. Command:

   prettier --write

   on TypeScript files
5. Create configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.parameters.file_path'); if [[ $FILE == *.ts ]]; then prettier --write \"$FILE\"; fi"
          }
        ]
      }
    ]
  }
}

1. Update

   .claude/settings.json

   safely
2. Suggest testing: "Edit a TypeScript file to see auto-formatting in action"

Advanced Patterns

Pattern: Conditional Execution

# Only run in specific directories
FILE=$(jq -r '.parameters.file_path')
if [[ $FILE == ./src/* ]]; then
  # Run command
fi

Pattern: Multiple Commands

# Chain multiple commands
FILE=$(jq -r '.parameters.file_path')
prettier --write "$FILE" && eslint --fix "$FILE"

Pattern: External Scripts

{
  "type": "command",
  "command": "/path/to/script.sh"
}

Pattern: Feedback to User

# Blocking hook with user-visible message
if [[ condition ]]; then
  echo "Error message shown to user" >&2
  exit 1
fi

Hook Development Workflow

1. Design: Identify event and purpose
2. Create: Generate hook configuration
3. Test Manually: Run command with sample JSON
4. Install: Update settings.json
5. Test Live: Trigger event in Claude Code
6. Iterate: Refine based on results
7. Document: Add comments explaining purpose

Testing Hooks Manually

# Create sample JSON
echo '{"toolName":"Edit","parameters":{"file_path":"test.ts"}}' | \
  jq -r '.parameters.file_path'

# Test your hook command
echo '{"toolName":"Edit","parameters":{"file_path":"test.ts"}}' | \
  FILE=$(jq -r '.parameters.file_path'); echo "Would format $FILE"

Security Considerations

1. Review commands carefully: Understand what they do
2. Avoid untrusted sources: Don't copy hooks without review
3. Limit scope: Use specific matchers, not always "*"
4. Test in isolation: Verify behavior before installing
5. Project hooks: Team members run these automatically (extra caution)

Remember

• Deterministic automation: Hooks ensure things always happen
• Keep it simple: Complex logic → external scripts
• Safe merging: Never break existing configuration
• Test before deploying: Especially for project-level hooks
• Clear purpose: Document what each hook does