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

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

• 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

• 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

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

undefined

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

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

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"

• 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"
          }
        ]
      }
    ]
  }
}

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

• ✓ 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)

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)

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"

Run command

undefined

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

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)

• 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