Hooks: Automated Guardrails

CLAUDE.md tells Claude what to do. Hooks make sure it actually happens - automatically, every time, without relying on the model to remember.

A hook is a script that runs in response to a Claude Code event. Edit a file? Auto-format it. About to run a dangerous command? Block it. Session ending? Run your test suite.

Hook Events

There are 7 events you can hook into:

Hook Types

Each hook has a type that determines how it runs:

command - Runs a shell command. The workhorse. Gets JSON on stdin, returns output on stdout.

http - Sends a POST request to a URL. Useful for webhooks and external integrations.

prompt - Asks the AI to make a decision based on the hook context. The model evaluates and decides whether to allow, deny, or modify.

Where Hooks Live

Hooks are configured in your settings files:

• .claude/settings.json - shared with team (committed)
• .claude/settings.local.json - personal (gitignored)

Exit Codes

For command hooks, the exit code determines what happens next:

Matchers

Hooks use glob patterns to match tool names. This is how you target specific tools:

"Edit"                  # Matches the Edit tool
"Edit|Write"            # Matches Edit OR Write
"Bash(npm *)"           # Matches Bash calls starting with "npm "
"Bash(rm *)"            # Matches Bash calls starting with "rm "
"*"                     # Matches everything (use sparingly)

The Data Flow

When a hook fires, it receives JSON on stdin with context about the event:

For PreToolUse and PostToolUse, the JSON includes tool_name, tool_input, and (for PostToolUse) tool_output:

{
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/app/src/utils.ts",
    "old_string": "...",
    "new_string": "..."
  }
}

Your hook script reads this JSON, does its work, and exits with the appropriate code.

Practical Examples

Auto-format on save

The most common hook. Every time Claude edits a file, run Prettier on it:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

This reads the edited file path from stdin JSON, pipes it to Prettier. Exit code 0 means "all good, carry on."

Block dangerous commands

Prevent Claude from running destructive commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm -rf *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCKED: rm -rf is not allowed' && exit 1"
          }
        ]
      }
    ]
  }
}

Exit code 1 means deny - the command never executes.

Run linter after file edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx eslint --fix"
          }
        ]
      }
    ]
  }
}

Ask for confirmation on force push

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push --force*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'This will force push. Are you sure?' && exit 2"
          }
        ]
      }
    ]
  }
}

Exit code 2 prompts the user to decide. The message is shown and they can approve or reject.

Combining Multiple Hooks

You can chain multiple hooks on the same event. They run in order - if any hook returns exit code 1, the chain stops:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          },
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx eslint --fix"
          }
        ]
      }
    ]
  }
}

Exercises

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm -rf *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCKED: rm -rf is prohibited. Remove files individually or use git clean for tracked files.' && exit 1"
          }
        ]
      }
    ]
  }
}