Creating Hooks

Table of Contents

• Official Documentation References
• What Are Claude Code Hooks?
• When to Use Hooks vs Skills/Commands
• Hook Creation Workflow
  • Step 1: Determine Hook Location
  • Step 2: Choose Hook Event Type
  • Step 3: Design Hook Matcher
  • Step 4: Write Hook Script
  • Step 5: Configure Hook in Settings
  • Step 6: Make Script Executable
  • Step 7: Test the Hook
• Hook Best Practices
• Common Hook Patterns
• Debugging Hooks
• Resources
• Quick Reference

What Are Claude Code Hooks?

Hooks are executable commands (typically scripts) that run in response to specific Claude Code events. They enable:

• Validation: Block or approve tool calls based on custom logic
• Automation: Run formatters, linters, or tests automatically
• Context injection: Add information to prompts or sessions
• Workflow control: Prevent Claude from stopping until criteria are met
• Observability: Log events, send notifications, track usage

When to Use Hooks vs Skills/Commands

Use hooks for:

• Event-driven automation (run when specific events occur)
• Cross-cutting concerns (apply to all projects or all tool calls)
• Real-time validation and approval workflows
• Context injection that happens automatically

Use skills for:

• Complex workflows requiring specialized knowledge
• Capabilities that Claude discovers and uses proactively
• Bundled resources (scripts, references, assets)

Use commands for:

• Explicit, user-invoked workflows
• Quick tasks with manual triggers
• Repeatable operations with preflight checks

Hook Creation Workflow

Follow this workflow to create hooks effectively.

Step 1: Determine Hook Location

Determine whether this should be a project hook (shared with team) or personal hook (just for you).

If unclear, ask: "Should this be a project hook (shared with team) or personal hook (just for you)?"

Project hooks (.claude/settings.json):

• Shared via git with the team
• Project-specific automation (e.g., run project tests, format with project tools)
• Located in project's .claude/ directory

Personal hooks (~/.claude/settings.json):

• Available across all projects for this user
• Personal preferences (e.g., notification style, personal validation rules)
• Located in user's home directory

Default behavior if not specified:

• If in a git repository with .claude/ directory → Project hook
• Otherwise → Personal hook

Step 2: Choose Hook Event Type

Based on the user's goal, select the appropriate hook event:

Common Events:

• PreToolUse - Validate/block tool calls before execution (matchers: tool names)
• PostToolUse - Run automation after tool completes (matchers: tool names)
• UserPromptSubmit - Inject context or validate prompts (no matcher)
• Stop - Verify completion before allowing Claude to stop (no matcher)
• SessionStart - Load context at session start (matchers: startup, resume, clear, compact)

Additional Events:

• SubagentStop - Control subagent completion (no matcher)
• SessionEnd - Cleanup on session end (no matcher)
• Notification - Observe notification events (no matcher)
• PreCompact - Save state before compaction (matchers: manual, auto)

See references/hook-events.md for complete event details, use cases, and selection guidance.

Step 3: Design Hook Matcher (if applicable)

For PreToolUse and PostToolUse events, specify which tools trigger the hook:

Exact match: "matcher": "Write" - Only Write tool Multiple tools: "matcher": "Write|Edit" - Write or Edit tools Pattern match: "matcher": "Notebook.*" - All Notebook tools All tools: "matcher": "*" or "matcher": "" - Every tool MCP tools: "matcher": "mcp__github__.*" - All GitHub MCP tools

For SessionStart: Use "matcher": "startup|resume" for specific sources For PreCompact: Use "matcher": "manual" or "matcher": "auto"

Other events don't use matchers - omit the matcher field entirely.

Step 4: Write Hook Script

Create the hook script that implements the desired behavior.

Script structure:

1. Read JSON input from stdin
2. Implement validation/automation logic
3. Output results via stdout/stderr or JSON
4. Exit with appropriate code

Exit codes:

• 0 - Success (stdout shown in transcript, except UserPromptSubmit/SessionStart which adds to context)
• 2 - Blocking error (stderr fed to Claude automatically)
• Other - Non-blocking error (stderr shown to user, execution continues)

Example script structure:

#!/usr/bin/env python3
import json
import sys

# Read input