Create Hook

Teaches Claude how to create automation hooks that trigger on specific events.

What is a Hook?

A hook is automation that runs when something happens. Hooks live in .claude/settings.json.

Key insight: Hooks make Claude proactive, not just reactive.

The 3-Phase Interview Process

When creating a NEW hook, guide the user through these phases:

Phase 1: TRIGGER

Ask the user:

• "When should this run?" (after writing a file, before a command, when session ends, etc.)
• "Should it run for all files or specific ones?"

Goal: Identify the event and matcher

Phase 2: ACTION

Ask the user:

• "What should happen when triggered?"
• "Should Claude think about it (prompt) or run a command (command)?"

Goal: Determine hook type and action

Phase 3: CONFIGURE

• Add the hook to settings.json
• Test it works

Hook Events

Hook Types

Prompt Hooks (Claude thinks)

Claude evaluates the prompt and decides what to do:

{
  "type": "prompt",
  "prompt": "If a file was created in the wrong location, suggest moving it."
}

Use when: You need Claude's judgment

Command Hooks (Run script)

Runs a bash command automatically:

{
  "type": "command",
  "command": "npm run lint --fix"
}

Use when: You want a specific command to run

Matchers

Matchers filter which tools trigger the hook:

settings.json Structure

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Your instruction here"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Summarize what was accomplished"
          }
        ]
      }
    ]
  }
}

Examples

Auto-update CLAUDE.md when skill created

{
  "matcher": "Write|Edit",
  "hooks": [{
    "type": "prompt",
    "prompt": "Check if a skill was just created or renamed in .claude/skills/. If so, update the CLAUDE.md routing table to include it."
  }]
}

Enforce output organization

{
  "matcher": "Write",
  "hooks": [{
    "type": "prompt",
    "prompt": "If a file was just created in the project root, suggest moving it to the appropriate folder (content/, research/, data/, exports/)."
  }]
}

Lint on save

{
  "matcher": "Write|Edit",
  "hooks": [{
    "type": "command",
    "command": "npm run lint --fix"
  }]
}

Session summary

{
  "hooks": [{
    "type": "prompt",
    "prompt": "Summarize what was accomplished this session in 2-3 bullet points."
  }]
}

(Note: Stop hooks don't use matchers)

Git commit reminder

{
  "matcher": "Write|Edit",
  "hooks": [{
    "type": "prompt",
    "prompt": "If 5+ files have been modified, remind the user to commit their changes."
  }]
}

Dangerous command warning

{
  "matcher": "Bash",
  "hooks": [{
    "type": "prompt",
    "prompt": "Check if this command could delete files or make irreversible changes. If so, warn the user."
  }]
}

Quick Setup Flow

When user wants to create a hook:

1. Identify the event - When should it trigger?
2. Choose hook type - Prompt (Claude thinks) or Command (run script)?
3. Write the hook - Add to settings.json
4. Test it - Trigger the event and verify it works

Creation Checklist

Before finalizing a hook, verify:

• Correct event chosen (PostToolUse, PreToolUse, Stop, etc.)
• Matcher is specific enough (avoid .* unless needed)
• Hook type matches the need (prompt vs command)
• Prompt is clear and actionable
• Tested by triggering the event

Common Mistakes

1. Too broad matcher - .* triggers on everything, use specific matchers
2. Wrong event - PostToolUse for after, PreToolUse for before
3. Vague prompt - Be specific about what Claude should do
4. Forgetting Stop hooks don't have matchers - They just fire when Claude stops
5. Not testing - Always trigger the hook to verify it works

Location: .claude/settings.json → hooks section Events: PreToolUse, PostToolUse, Stop, SubagentStop, UserPromptSubmit