Claude Code Hooks: Automate Formatting, Tests, and Guardrails

Claude Code hooks are user-defined commands that run automatically at specific points in Claude Code's lifecycle — before a tool call, after a file edit, when you submit a prompt, when the session starts or ends. They are the difference between asking the agent to follow a rule and enforcing it.

Instructions ask. Hooks guarantee.

You can write "always run prettier after editing a file" in CLAUDE.md, and Claude will usually do it. But "usually" is doing real work in that sentence: instructions compete with everything else in context, and in a long session they can be deprioritized or compacted away. A hook removes the model from the loop entirely — the formatter runs after every edit because the harness runs it, not because the model remembered to.

That's the mental model for what belongs where:

• Judgment calls (naming, architecture, tone) → CLAUDE.md instructions.
• Invariants (formatting, protected files, notifications, audit logs) → hooks.

What teams actually use hooks for

• Auto-formatting — run prettier, ruff, or gofmt on every file Claude edits.
• Guardrails — block edits to .env files, lockfiles, or migrations; gate dangerous Bash patterns beyond what permission rules express.
• Feedback loops — run the affected tests after an edit and feed failures straight back to Claude.
• Notifications — desktop ping when Claude needs input or finishes a long task.
• Audit and compliance — log every tool call with its input to a file your team can review.

The hook events

The core events, and whether they can block the action:

More specialized events exist — PermissionRequest, FileChanged, worktree and subagent lifecycle events, and others — and the list grows with the product; the docs' hooks reference is the source of truth for the full set. The two you'll use most are PreToolUse (gate things) and PostToolUse (react to things).

Configuring a hook

Hooks live under the hooks key in any settings file — ~/.claude/settings.json for every project, .claude/settings.json to share with your team, .claude/settings.local.json to keep personal. Each event maps to a list of matchers, and each matcher to a list of handlers:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-after-edit.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

• matcher filters which tool triggers the hook — an exact tool name (Bash), an alternation (Edit|Write), or * for everything. MCP tools match by their full name (mcp__github__create_issue).
• type: "command" is the workhorse. Other handler types exist — prompt and agent hooks that ask a model to evaluate a condition, HTTP hooks that POST the event to a URL — but start with commands.
• timeout caps how long the hook may run, in seconds.

Run /hooks in a session to see every registered hook and which settings file it came from, and set "disableAllHooks": true to switch them off temporarily.

How a hook talks back

Every hook receives the event as JSON on stdin:

{
  "session_id": "abc123",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Edit",
  "tool_input": { "file_path": "/path/to/project/src/index.ts" }
}

It answers with its exit code, and optionally with JSON on stdout:

• Exit 0 — success. Stdout may contain JSON for fine-grained control.
• Exit 2 — block, for events that support it. For PreToolUse the tool call never runs, and your stderr is shown to Claude as the reason.
• Anything else — non-blocking error; the session continues.

The JSON output unlocks the precise controls: a PreToolUse hook can return "permissionDecision": "allow" | "ask" | "deny" with a reason, any hook can add "additionalContext" for Claude or a "systemMessage" for you, and "continue": false stops the session outright.

Three hooks worth copying

1. Format after every edit (PostToolUse, matcher Edit|Write):

#!/usr/bin/env bash
# .claude/hooks/format-after-edit.sh
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$file" >/dev/null 2>&1 ;;
  *.py) ruff format "$file" >/dev/null 2>&1 ;;
esac
exit 0

2. Protect paths Claude should never touch (PreToolUse, matcher Edit|Write):

#!/usr/bin/env bash
# .claude/hooks/protect-paths.sh
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.env*|*/secrets/*|*.pem|*package-lock.json|*pnpm-lock.yaml)
    echo "Blocked: $file is protected. Change it manually if it really must change." >&2
    exit 2 ;;
esac
exit 0

Exit code 2 blocks the edit, and the stderr line tells Claude why, so it routes around the restriction instead of retrying it.

3. Desktop notification when Claude needs you (Notification):

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

(macOS; on Linux swap in notify-send "Claude Code" "Claude needs input".) Kick off a long task, go do something else, and let the hook pull you back.

Hooks run as you

A hook is arbitrary code executing with your credentials, inside your session. Treat the mechanism with respect:

• Review third-party hooks. A repo's checked-in .claude/settings.json can register hooks; read them before working in an untrusted repo, the same way you'd read a postinstall script.
• Quote and validate. Hook input contains model-chosen values (file paths, commands). Quote every variable and handle unexpected shapes — your protect-paths hook shouldn't be injectable through a weird filename.
• Decide fail-open vs. fail-closed. A formatter that errors should probably exit 0 (fail open); a compliance gate should exit 2 on any doubt (fail closed).
• Keep them fast. Hooks run inline; a slow PreToolUse hook taxes every single tool call.

Hooks are one of the three pillars that make Claude Code programmable — alongside settings and permissions and memory. Wire all three and the agent stops being a chat window and starts being infrastructure: running unattended in CI with the same guardrails you use locally.