Extract as Hook

Hooks automate actions on events (edit, save, permission, etc.).

1. Detection Signals

Extract a hook when:

• You repeatedly do the same check/format manually
• You say "I wish this would automatically..."
• Same validation appears in multiple sessions
• Pattern: "After I do X, I always do Y"
• Examples:
  • "I always run prettier after editing"
  • "I always run tests before committing"
  • "I always check this file isn't edited"

2. Identify the Trigger Event

Hooks fire on these events:

File Operations:

• PostToolUse — after editing/writing files
• PreToolUse — before certain operations

Session Events:

• UserPromptSubmit — on every user message
• SessionStart — when session begins
• SessionEnd — when session ends

Permission Events:

• PermissionRequest — when permission needed
• PostToolUseFailure — when tool fails

Other:

• PreCompact — before context compaction
• Notification — when notification happens

3. Identify the Action Type

Hooks can do:

Command hooks — run shell commands

{
  "type": "command",
  "command": "black $EDITED_FILE"
}

Prompt hooks — Claude makes yes/no decision

{
  "type": "prompt",
  "prompt": "Should I run tests?"
}

Agent hooks — subagent does something

{
  "type": "agent",
  "agent": "code-reviewer"
}

4. Define Scope

Choose where hook applies:

System-wide (all projects):

~/.claude/settings.json

Project-specific:

.claude/settings.json

Local only (gitignored):

.claude/settings.local.json

5. Write the Hook

Template:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit.*\\.py",
        "hooks": [
          {
            "type": "command",
            "command": "black $EDITED_FILE 2>/dev/null && echo '✓ Auto-formatted'"
          }
        ]
      }
    ]
  }
}

Components:

• matcher — regex pattern (which files/tools trigger this?)
• command — shell command to run
• type — "command", "prompt", or "agent"

6. Environment Variables

Available in hook commands:

• $EDITED_FILE — path of file being edited
• $TOOL_NAME — which tool was used
• $EXIT_CODE — if tool failed
• $CLAUDE_SESSION_ID — current session ID

Example:

{
  "command": "echo 'Edited: $EDITED_FILE' && npx eslint --fix '$EDITED_FILE'"
}

7. Test the Hook

After creating:

1. Trigger the event (edit a matching file)
2. Verify the hook runs
3. Check the action completed
4. Adjust command/matcher if needed

Common Hooks to Create

Auto-Format on Edit

{
  "PostToolUse": [
    {
      "matcher": "Edit.*\\.py",
      "hooks": [{
        "type": "command",
        "command": "black '$EDITED_FILE' --quiet 2>/dev/null || true"
      }]
    }
  ]
}

Lint on Write

{
  "PostToolUse": [
    {
      "matcher": "Write.*\\.ts",
      "hooks": [{
        "type": "command",
        "command": "npx eslint --fix '$EDITED_FILE' 2>/dev/null || true"
      }]
    }
  ]
}

Validate JSON

{
  "PostToolUse": [
    {
      "matcher": "Write.*\\.json",
      "hooks": [{
        "type": "command",
        "command": "python -m json.tool '$EDITED_FILE' > /dev/null && echo '✓ Valid JSON'"
      }]
    }
  ]
}

Protect Critical Files

{
  "PreToolUse": [
    {
      "matcher": "Edit.*(\\.env|secrets|credentials|private_key)",
      "hooks": [{
        "type": "prompt",
        "prompt": "About to edit a sensitive file. Continue?"
      }]
    }
  ]
}

Run Tests Before Commit

{
  "UserPromptSubmit": [
    {
      "matcher": "commit",
      "hooks": [{
        "type": "command",
        "command": "npm test 2>&1 | head -20"
      }]
    }
  ]
}

8. Hook File Structure

Create/update settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "pattern1",
        "hooks": [action1, action2, ...]
      },
      {
        "matcher": "pattern2",
        "hooks": [action3, ...]
      }
    ],
    "PreToolUse": [
      ...
    ]
  }
}

Example Output

✓ Hook created: ~/.claude/settings.json
Trigger: PostToolUse on .py files
Action: Auto-format with black

From now on:
1. You edit a Python file
2. I automatically run: black $EDITED_FILE
3. You get formatted code without asking

Tips

• Keep commands fast (users notice delays)
• Suppress output with 2>/dev/null || true
• Use exit code 2 in commands to block the action
• Test hooks locally first before making system-wide
• Document why in comments if hook is non-obvious