create-hook

Core principle: prefer dispatchers over standalone hooks. When multiple hooks exist on the same event, they should be consolidated into a single dispatcher with a checks/ directory. This eliminates redundant JSON parsing, prevents conflicts, and makes adding new checks trivial (drop a file). The create-hook flow automatically detects when a dispatcher should be used and routes accordingly.

If bare /create-hook with no arguments, ask:

What do you need?

1. Create a new hook - I'll check your existing hooks first. If you already have a dispatcher or multiple hooks on the same event, I'll add a check to the dispatcher instead of creating a standalone hook.
2. Edit an existing hook - Modify a hook or dispatcher check in .claude/hooks/
3. Consolidate hooks - Migrate multiple standalone hooks into a single dispatcher
4. Debug a hook - Something's not working? Let's figure out why
5. View hook logs - See which hooks are firing (scripts/hook-log.py)
6. Validate hooks - Check that hooks are correctly configured and ready for use
7. Analyze hooks - See what hooks you have running and find gaps
8. Something else - Templates, settings, MCP tools, security, env vars

When creating a new hook, ALWAYS ask about installation level:

Where should this hook be installed?

1. Project level (.claude/settings.json) - Runs only in THIS project, checked into git
2. User level (~/.claude/settings.json) - Runs in ALL your projects
3. Local only (.claude/settings.local.json) - Project-level but gitignored (for personal/sensitive hooks)

Intent	References to Load	Workflow
Create new hook	hook-events.md, json-output.md, security.md, sub-agents.md, dispatcher-pattern.md	Spawn inventory agent → dispatcher decision → create (check or standalone) → tester agent
Create prompt-based hook	prompt-based-hooks.md, hook-events.md	Determine event → configure prompt → test
Create component-scoped hook	component-scoped-hooks.md, hook-events.md	Define in frontmatter → test
Edit existing hook	hook-events.md, json-output.md, debugging.md	Read existing hook → modify → test
Debug hook	debugging.md, hook-events.md	Diagnose → fix → test
Validate hooks	debugging.md	Run scripts/validate-hook.py --project
View hook logs	debugging.md	Run scripts/hook-log.py or tail -f .claude/hooks/.debug.log
Analyze hooks	sub-agents.md	Spawn inventory agent
Consolidate hooks (dispatcher)	dispatcher-pattern.md, hook-events.md	workflows/create-dispatcher.md
MCP tools	mcp-tools.md, hook-events.md	Show patterns
SessionStart/env vars	session-env-vars.md, hook-events.md	Show patterns
Security review	security.md	Show checklist
Templates	(load template file directly)	Show template
Add to settings	workflows/add-to-settings.md	Configure

<essential_principles>

1. Analyze first - Before creating, understand existing hooks to prevent conflicts
2. Dispatcher by default - After inventory, check if a dispatcher exists or should be created:
   • Dispatcher exists for this event → Add a check script to checks/, not a standalone hook
   • 2+ hooks already exist on this event → Recommend consolidating into a dispatcher first
   • 0-1 hooks exist → Create standalone hook (but keep it dispatcher-ready) See references/dispatcher-pattern.md for the full pattern.
3. Ask installation level - ALWAYS ask user: project, user, or local level
   • Project (.claude/settings.json) - This project only, version controlled
   • User (~/.claude/settings.json) - ALL projects for this user
   • Local (.claude/settings.local.json) - This project only, gitignored
4. Debug wrapper by default - Always include debug-wrap.sh and wrap commands with it (user can opt out)
5. Input via stdin - Hooks receive JSON with session_id, tool_name, tool_input, etc.
6. Output via exit codes - 0=success, 2=blocking error (stderr shown to Claude)
7. Parallel execution - All matching hooks run simultaneously (60s timeout default)
8. Validate after creation - Run scripts/validate-hook.py to confirm proper installation </essential_principles>