Hooks: Event-Driven Automation

In the world of Claude Code, Hooks are an event-driven automation mechanism. They are shell commands you pre-configure that execute automatically at specific lifecycle events within Claude Code. Think of them like Git Hooks — just as pre-commit and post-commit hooks work, Claude Code Hooks let you inject custom logic before and after tool calls.

Unlike letting Claude autonomously decide whether to perform an action, Hooks provide deterministic guarantees: as long as the event fires, the command will execute. This is crucial for code formatting, linting, security enforcement, and similar scenarios.

Hook Types

Claude Code supports five Hook event types:

The most commonly used are PreToolUse and PostToolUse, which let you inject custom behavior before and after tool calls.

Configuration Format

Hooks are configured in .claude/settings.json (project-level) or ~/.claude/settings.json (user-level). The structure looks like this:

{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Write",
      "command": "echo 'About to write a file: $CLAUDE_FILE_PATH'"
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Write",
      "command": "npx prettier --write $CLAUDE_FILE_PATH"
    }
  ],
  "Stop": [
    {
      "command": "echo 'Claude has finished responding'"
    }
  ]
}
}

Each Hook entry contains:

• matcher (optional): A string to match tool names. The Hook fires only when the tool name matches. Omitting matcher means it matches all tools.
• command: The shell command to execute.

Matcher Rules

The matcher field filters which tools trigger the Hook. It matches against tool names:

// Only fires on Write tool calls
{ "matcher": "Write", "command": "..." }

// Only fires on Bash tool calls
{ "matcher": "Bash", "command": "..." }

// Fires on any tool call (matcher omitted)
{ "command": "..." }

Environment Variables

When a Hook command executes, Claude Code injects several environment variables so your script can access context about the current operation:

• $CLAUDE_FILE_PATH — The file path being operated on
• $CLAUDE_TOOL_NAME — The name of the tool that triggered the Hook
• $CLAUDE_TOOL_INPUT — The tool’s input parameters (JSON format)
• $CLAUDE_TOOL_OUTPUT — The tool’s output result (PostToolUse only)

Blocking Mechanism

PreToolUse Hooks have a powerful capability: if the Hook command exits with a non-zero exit code, Claude Code will block the tool from executing. This lets you build security guardrails.

Example: Auto-Formatting

Automatically run Prettier after every file write by Claude:

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
    }
  ]
}
}

Note the trailing || true — this ensures that even if Prettier encounters an unsupported file type, it won’t cause an error.

Example: Blocking Dangerous Commands

Use a PreToolUse Hook to intercept dangerous shell commands:

{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "command": "echo $CLAUDE_TOOL_INPUT | grep -q 'rm -rf /' && echo 'BLOCKED: dangerous rm -rf command' && exit 1 || exit 0"
    }
  ]
}
}

When Claude attempts to execute a command containing rm -rf /, the Hook detects the dangerous pattern, outputs a warning message, and exits with a non-zero code, blocking execution. Claude receives the Hook’s output and adjusts its behavior accordingly.

Example: Auto-Testing

Automatically run the corresponding test after editing a test file:

{
"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "command": "echo $CLAUDE_FILE_PATH | grep -q '\.test\.' && npm test -- --testPathPattern=$CLAUDE_FILE_PATH || true"
    }
  ]
}
}

Hook Output Feedback

A Hook’s standard output (stdout) is captured by Claude Code and fed back to the Claude model. This means Hooks can not only perform actions but also influence Claude’s subsequent behavior. For instance, error messages output by a lint Hook will prompt Claude to automatically fix code issues.

Best Practices

• Keep commands lightweight: Hooks execute synchronously — long-running commands block Claude’s response.
• Handle errors gracefully: Use || true or 2>/dev/null to avoid unintended Hook failures blocking tools.
• Use PreToolUse for guardrails: Deterministically block dangerous operations rather than relying on Claude’s judgment.
• Use PostToolUse for post-processing: Put formatting, linting, and testing after tool execution.
• Project-level vs user-level: Team-shared rules go in .claude/settings.json; personal preferences go in ~/.claude/settings.json.