Hooks in Claude Code

What are hooks?

Hooks are user-defined automations that Claude Code calls at specific points during a session. You define them in your settings.json. When an event fires — before a tool runs, after a file is written, when a session starts — Claude Code passes JSON context to your handler and optionally acts on what it returns.

Hook lifecycle

Events fire in a predictable order. Each event is a named point where Claude Code can call your hook.

Configuration structure

Hooks live in .claude/settings.json (or your user-level settings). The JSON has three nesting levels: event → matcher → handler.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [            // → Level 1: hook event
      {
        "matcher": "Write|Edit", // → Level 2: match Write or Edit tool
        "hooks": [
          {
            "type": "command",   // → Level 3: handler type
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

Hook types

Each handler has a type field. Choose the right type based on what you want the hook to do.

Exit codes (command hooks)

How your script exits tells Claude Code what to do next.

Worked example: auto-format Python files

Every time Claude writes or edits a .py file, automatically run the Black formatter on it — so the codebase stays clean without any manual steps.

#!/bin/bash
# .claude/hooks/format-python.sh

# Read the JSON that Claude Code sends on stdin
INPUT=$(cat)

# Extract the file path that was just written or edited
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Only format Python files
if [[ "$FILE" == *.py ]]; then
  black "$FILE" 2>/dev/null
fi

exit 0   # always exit 0 — formatting is a side-effect, not a gate

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-python.sh",
            "statusMessage": "Formatting Python…"
          }
        ]
      }
    ]
  }
}

/hooks
# Opens a read-only browser showing:
# PostToolUse [1]
#   matcher: Write|Edit
#   type: command
#   source: Project (.claude/settings.json)
#   command: "$CLAUDE_PROJECT_DIR"/.claude/hooks/format-python.sh

Key events reference

* PostToolUse can return decision: "block" in JSON to prompt Claude with a reason — the tool already ran but Claude is asked to reconsider.

Where to define hooks

The location of the settings file determines the scope of the hook.

Three useful patterns

1. Block a dangerous command (PreToolUse)

Return exit 2 from a script when the command is unsafe. Claude sees the stderr message as the reason.

#!/bin/bash
CMD=$(cat | jq -r '.tool_input.command // empty')

# Block any command that removes the database directory
if echo "$CMD" | grep -q 'rm.*db/'; then
  echo "Blocked: removing the database directory is not allowed" >&2
  exit 2
fi

exit 0

2. Inject context at session start (SessionStart)

Print plain text to stdout on exit 0 — Claude Code adds it to Claude's context before the first prompt.

#!/bin/bash
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
CHANGES=$(git status --short 2>/dev/null | wc -l | tr -d ' ')

echo "Current branch: $BRANCH"
echo "Uncommitted files: $CHANGES"

exit 0

3. Enforce quality before Claude stops (Stop)

Return { "decision": "block", "reason": "..." } to keep Claude working until your quality gate passes.

#!/bin/bash
# Run the type-checker; if it fails, stop Claude from stopping
if ! npx tsc --noEmit 2>/dev/null; then
  echo '{
    "decision": "block",
    "reason": "TypeScript errors found — fix them before finishing"
  }'
fi

exit 0

Before you continue

• Hooks fire at lifecycle events — SessionStart, PreToolUse, PostToolUse, Stop, and more.
• Config nests as event → matcher → handler inside settings.json.
• Use exit 2 to block an action; exit 0 lets it proceed.
• Inspect hooks with /hooks; use $CLAUDE_PROJECT_DIR for script paths.
• Next lesson: Memory Management — how Claude remembers context across sessions.

What's Next

Hooks give you fine-grained control over Claude's actions. Next: Memory Management — how Claude remembers context across sessions.