Hooks: Event-Driven Automation

Hooks are your commands that run automatically when Claude does something.

• Claude edits a file → your formatting command runs
• Claude runs a bash command → your logging command runs
• You submit a prompt → your context injection runs
• Session starts → your setup script runs

Why this matters: You can tell Claude "always format code after editing"—but it might forget. A hook guarantees it happens every time, because it's your code running automatically, not Claude choosing to run it.

---

Why Hooks?

Without hooks, you hope Claude remembers to:

• Format code after editing
• Run tests after changes
• Follow your naming conventions
• Avoid touching sensitive files

With hooks, you guarantee these happen:

• PostToolUse hook runs Prettier after every file edit
• PreToolUse hook blocks edits to .env files
• SessionStart hook loads project context automatically
• Notification hook sends Slack alerts when Claude needs input

The key insight: By encoding rules as hooks instead of prompting instructions, you turn suggestions into app-level code that executes every time.

---

The Five Main Hook Events

There are also advanced events (Stop, SubagentStop, PermissionRequest, Notification) for specialized workflows.

---

How Hooks Work

The pattern:

1. An event occurs (e.g., you submit a prompt)
2. Claude Code runs your hook script
3. Script receives JSON input via stdin
4. Script produces output via stdout
5. Output gets injected into Claude's context

Exit codes matter:

• 0 = Success (stdout processed)
• 2 = Block the action (show error)
• Other = Non-blocking warning

---

Configuring Hooks

Option 1: Use the /hooks Command (Easiest)

Run:

This opens an interactive menu where you:

1. Select an event (PreToolUse, PostToolUse, etc.)
2. Add a matcher (which tools to match)
3. Add your hook command
4. Choose storage location (User or Project)

Option 2: Edit settings.json Directly

Hooks are configured in .claude/settings.json:

Key fields:

• EventName: Which event triggers this (PreToolUse, PostToolUse, etc.)
• matcher: Which tools to match (e.g., Bash, Write, Edit, Read)
• command: The script to run

Matcher Patterns

---

Try It Now: Your First Hook

Let's log every Bash command Claude runs.

Prerequisite: Install jq for JSON processing (brew install jq on macOS, apt install jq on Linux).

Method 1: Using /hooks (Quickest)

1. Run /hooks in Claude Code

2. Select PreToolUse

3. Add matcher: Bash

4. Add hook command:

   Specification

   WrapCopy

   jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-log.txt

5. Choose User settings for storage

6. Press Esc to save

Now ask Claude to run ls and check your log:

Method 2: Edit settings.json Directly

Add to .claude/settings.json:

Restart Claude Code and test it.

---

Real Example: UserPromptSubmit Hook

Here's a real hook that tracks prompts (from this book's codebase):

Script (.claude/hooks/track-prompt.sh):

Configuration:

What happens:

1. You submit a prompt
2. Hook receives JSON: {"prompt": "your message", "session_id": "..."}
3. Script extracts prompt, logs it with timestamp
4. Session continues normally

---

Real Example: PreToolUse Hook

Track when skills are invoked:

Configuration:

What this does:

• Fires before the Skill tool runs
• Only matches the Skill tool (not Bash, Write, etc.)
• Can log, validate, or modify the tool call

---

Real Example: PostToolUse Hook

Track subagent results:

Configuration:

What this does:

• Fires after the Task tool completes
• Receives the task result in JSON input
• Can log, analyze, or trigger follow-up actions

---

Hook Input Format

All hooks receive JSON via stdin. Common fields:

Event-specific fields:

• UserPromptSubmit: {"prompt": "user's message"}
• PreToolUse/PostToolUse: {"tool_name": "...", "tool_input": {...}}
• SessionStart: Basic session info

---

Hook Output Format

Simple: Just print text to stdout:

Advanced: Output JSON for more control:

Block an action:

---

Combining Multiple Hooks

You can have multiple hooks for the same event:

Different matchers trigger different scripts based on which tool is used.

---

Debugging Hooks

If hooks aren't working:

1. Check the script is executable: chmod +x .claude/hooks/your-script.sh
2. Test manually: echo '{"test": "data"}' | bash .claude/hooks/your-script.sh
3. Check settings.json syntax: Valid JSON? Correct structure?
4. Use debug mode: claude --debug shows hook execution

---

Where Hooks Live

Tip: Use a _common.sh file for shared functions like JSON parsing.

---

Try With AI

📝 Create a Simple Hook:

"Help me create a SessionStart hook that shows the git branch and last commit message when I start Claude Code. Walk me through: the script, the settings.json config, and how to test it."

What you're learning: The complete hook lifecycle—from script to configuration to testing. This pattern applies to all hook types.

🔍 Understand Hook Events:

"I want to automatically run prettier after Claude edits a JavaScript file. Which hook event should I use? What would the matcher be? Show me the complete configuration."

What you're learning: Event selection and pattern matching—choosing the right trigger and scope for automated behavior.

🛡️ Validation Hook:

"Help me create a PreToolUse hook that warns me before Claude runs any command with 'rm' or 'delete' in it. The hook should print a warning but not block the command."

What you're learning: Safety guardrails through hooks—implementing "soft" warnings that inform without blocking, a pattern used in production systems.

📊 Logging Hook:

"I want to log all the tools Claude uses during a session. Help me create a PostToolUse hook that appends tool names and timestamps to a log file."

What you're learning: Observability through hooks—instrumenting AI behavior for debugging and analysis. This is how production systems gain visibility.

🔧 Debug a Hook:

"My hook isn't running. Help me debug: How do I test the script manually? How do I check if settings.json is correct? What does claude --debug show?"

What you're learning: Hook debugging methodology—the systematic approach when automation doesn't work. This skill saves significant debugging time.