Hooks — Automate Everything

🧠 Knowledge Check

Q: What's the key difference between hooks and skills?

Hooks are deterministic — they always run when their event fires. Skills are optional — Claude decides whether to invoke them based on the task. Use hooks for things that must happen (formatting, blocking, notifications) and skills for things Claude should consider doing.

Hook Structure

Matchers

• Empty string "" → matches all events
• Tool name "Bash" → matches that tool
• Pattern "Edit|Write" → matches either tool
• Compaction "compact" → matches compaction events (SessionStart)

Input & Output

Hook Input (stdin)

Every hook receives JSON on stdin with event-specific data:

Hook Output (exit codes)

This is crucial: Exit code 2 is your power move. It lets hooks block tool calls and feed reasons back to Claude.

🧠 Knowledge Check

Q: A PreToolUse hook exits with code 2 and prints "Use rg instead of grep" to stderr. What happens?

The tool call is blocked. Claude receives the stderr message ("Use rg instead of grep") as feedback and will adjust its approach — likely switching to rg for the search.

Practical Examples

Desktop Notifications

Get alerted when Claude needs your input:

Auto-Format After Edits

Run Prettier on every file Claude edits:

Block Protected Files

Re-inject Context After Compaction

Block Dangerous SQL

✍️ Recall Exercise

Fill in the blanks:

• Exit code to block a tool call: ___
• Hook that fires after compaction: SessionStart with matcher "___"
• To interactively set up hooks: /___

• 2
• compact
• /hooks

Hook Types

Command Hooks (Default)

Run a shell command. The most common type:

Prompt-Based Hooks

Use a Claude model for single-turn evaluation:

Agent-Based Hooks

Multi-turn verification with tool access:

🧠 Knowledge Check

Q: When would you use an agent-based hook instead of a command hook?

Use agent-based hooks when verification requires AI reasoning and multi-step analysis — like checking whether code changes break an API contract or violate security policies. Agent hooks get their own tools (Read, Grep, etc.) and can do complex analysis. Use command hooks for deterministic actions like formatting, blocking known patterns, or sending notifications.

Execution Model

• All matching hooks for an event run in parallel
• Identical hook commands are deduplicated
• For PreToolUse: any hook returning exit 2 blocks the action
• Toggle verbose mode with Ctrl+O to see hook execution logs

Environment Variables in Hooks

Hooks can persist environment variables using CLAUDE_ENV_FILE:

✍️ Recall Exercise

Fill in the blanks:

• Hooks run in ___ (parallel/sequential)
• The three hook types are: command, ___, and agent
• To see hook execution logs: Ctrl+___

• parallel
• prompt
• Ctrl+O (verbose mode)

🔨 Try It Yourself

1. Add a PostToolUse hook that logs every file Claude edits:

   {
     "hooks": {
       "PostToolUse": [{
         "matcher": "Edit|Write",
         "hooks": [{
           "type": "command",
           "command": "jq -r '.tool_input.file_path' >> /tmp/claude-edits.log"
         }]
       }]
     }
   }
   

2. Add this to your .claude/settings.local.json
3. Start a session and ask Claude to edit a file
4. Check /tmp/claude-edits.log to see the logged path
5. Try adding a PreToolUse hook that blocks edits to README.md

Reflection: How could you combine hooks to build an automated code quality pipeline?

🤔 What Would You Do?

Scenario: Your team runs a Python project where Claude keeps using pip instead of poetry. You want to automatically redirect it without manual intervention.

Create a PreToolUse hook that detects pip commands and blocks them with guidance:

Claude receives the feedback and switches to poetry. This is deterministic — it works every time, unlike CLAUDE.md instructions which Claude might occasionally ignore.

📋 Key Takeaways (Review These Tomorrow)

Next up: Skills — Reusable Commands → — Build markdown-based playbooks that Claude follows on demand.