workflow-add-hook

Add New Hook

Add a new Claude Code hook event to the claude-code-hooks project.

Hook event name: $ARGUMENTS (if empty, ask the user)

Naming rules:

• Hook name is PascalCase (e.g. ConfigChange, PreToolUse)
• Sound folder/files use lowercase with no separators (e.g. configchange, pretooluse)

---

Step 0: Validate

If $ARGUMENTS is empty, ask the user for the hook event name. Confirm it's PascalCase. Derive the lowercase version.

Step 1: Check Sound Files (BLOCKING)

Check if .claude/hooks/sounds/<lowercase>/ exists with <lowercase>.mp3 and <lowercase>.wav.

• If missing: Create the directory, tell the user to add sound files (suggest ElevenLabs with voice "Samara X"), and STOP. Do NOT proceed until the user confirms files are added.
• If present: Continue to Step 2.

Step 2: Research the Hook

Fetch all three sources in parallel using WebFetch:

1. Hooks Reference — Find the hook's description, matcher support, can-block status, and special requirements
2. Hooks Guide — Find hook types, matcher values with examples, environment variables, and additional usage details
3. Changelog — Find which Claude Code version introduced this hook

Never ask the user for version or description — always look it up.

Step 3: Determine Hook Properties

Property	Rule
timeout	Default 5000. Use 30000 only for heavy init hooks (like Setup)
once	Only for session-lifecycle hooks (like SessionStart, SessionEnd, PreCompact). Ask user if unsure, default to false
async	Always true (all hooks in this project are async sound notifications)

Step 4: Update All Files

Read each file first, then edit. ALL files must be updated — no exceptions.

Settings files (4 files)

Add the hook entry in correct position. Structure:

"<HookEventName>": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
        "timeout": <timeout>,
        "async": true,
        "statusMessage": "<HookEventName>"
      }
    ]
  }
]