Claude Code Hooks: Automate Your Workflow with Lifecycle Events

Key Takeaways#

• Hooks are shell commands, HTTP requests, or MCP tool invocations that fire automatically at defined points in Claude Code's lifecycle — no manual triggering required.
• They receive structured JSON context about the triggering event and can optionally return decisions (allow, block, or modify behavior) via exit codes or JSON output.
• Configuration lives in three levels: hook event, matcher group, and hook handlers — giving you fine-grained control over which tools, files, or patterns trigger which actions.
• Scope ranges from personal (user-level settings) to project (committable .claude/settings.json) to org-wide (managed policy), so teams can enforce standards consistently.
• Practical uses include auto-formatting on save, blocking dangerous shell commands, audit-logging file changes, and preventing context loss during compaction.

What Are Hooks?#

Hooks are event-driven automations attached to Claude Code's lifecycle. When a specific event fires — say, a tool is about to run or a session starts — Claude Code checks whether any hooks are configured for that event. If so, it executes each hook handler in order, passing a JSON payload describing the event context.

A hook can be:

• A shell command (type: "command") — runs in a subprocess, receives JSON on stdin, returns decisions via exit codes or stdout JSON.
• An HTTP request (type: "http") — sends a POST (or other method) with the event payload to a URL you specify.
• An MCP tool call (type: "mcp_tool") — invokes an MCP server tool directly with parameters derived from the event context.

Hooks are not callbacks in the traditional sense. They execute in their own subprocess or network context. They cannot mutate Claude Code's internal state directly, but they can influence behavior: a hook that exits with code 2 can block the action that triggered it, and a hook that outputs specific JSON can supply additional decisions.

Lifecycle Events#

Claude Code exposes hooks at many points in its lifecycle. Here are the key events:

Configuration Structure#

Hooks are configured in a three-level hierarchy:

1. Hook event — the top-level key (e.g., PreToolUse) that maps to an array of matcher groups.
2. Matcher group — an object with an optional matcher pattern and an array of hooks (handlers).
3. Hook handlers — individual hook definitions with type, command/url/tool, and optional settings.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "validate-bash-command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

Multiple matcher groups under the same event are evaluated in order. All matching handlers run sequentially.

Hook Locations and Scope#

Where you place hook configuration determines its scope:

Project-level settings (.claude/settings.json) are ideal for team-wide hooks like auto-formatting or lint gates. User-level settings (~/.claude/settings.json) are for personal preferences. Managed policy lets enterprise admins enforce hooks that users cannot override.

Matcher Patterns#

Matchers filter which tool calls (or other targets) trigger a hook group. Three formats are supported:

• Exact string: "Edit" — matches only the tool named Edit.
• Pipe-separated: "Edit|Write|MultiEdit" — matches any of the listed tools.
• Regex: "Bash(mkdir|rm).*" — matches tools by regex pattern.

The target of a matcher depends on the event type:

If no matcher is specified, the hook group fires for all occurrences of that event.

Practical Examples#

1. Auto-Format After Edits#

Run Prettier on every file that Claude edits or writes:

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

The CLAUDE_FILE_PATH environment variable is set automatically by Claude Code when a file-editing tool fires. The hook runs silently — if it fails, Claude Code logs a warning but does not block the workflow.

2. Block Dangerous Shell Commands#

Prevent rm -rf / and similar destructive patterns before they execute:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | grep -iP 'rm\\s+(-[a-zA-Z]*f[a-zA-Z]*\\s+|--)\\\\?/(\\\\s|$)' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

Exit code 2 is the signal to block the tool call. Claude Code will not execute the blocked command and will inform the user. Exit code 0 allows the tool call to proceed.

3. Audit Log All File Changes#

Write an audit trail for compliance or debugging:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"{\\\"time\\\":\\\"$(date -Iso8601)\\\",\\\"file\\\":\\\"$CLAUDE_FILE_PATH\\\",\\\"tool\\\":\\\"$CLAUDE_TOOL_NAME\\\"}\" >> .claude/audit-log.jsonl"
          }
        ]
      }
    ]
  }
}

This appends a JSON Lines entry for every file mutation. The log is committable if placed in .claude/, making it easy to track what Claude changed and when.

4. Block Compaction and Inject a Handoff Doc#

Prevent context loss during compaction by forcing Claude to write a handoff document first:

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat <<'MSG'\nCompaction blocked. Write a handoff document summarizing current state before compacting.\nMSG\nexit 2"
          }
        ]
      }
    ]
  }
}

When a PreCompact hook exits with code 2, compaction is blocked. The stdout text is shown to Claude as the reason, prompting it to create a handoff summary before retrying.

HTTP Hooks#

Hooks can make HTTP requests instead of running local commands. This is useful for sending events to dashboards, Slack webhooks, or custom APIs.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/claude-events",
            "method": "POST",
            "headers": {
              "Authorization": "Bearer $CLAUDE_HOOK_TOKEN",
              "Content-Type": "application/json"
            }
          }
        ]
      }
    ]
  }
}

The event payload is sent as the request body. Header values can reference environment variables for secrets. HTTP hooks that return a non-2xx status code are treated as failures; for PreToolUse events, a 4xx/5xx response blocks the tool call.

Hooks Invoking MCP Tools#

Hooks can call MCP (Model Context Protocol) tools directly. This lets you trigger actions in external services without writing glue scripts:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my-ci-server",
            "tool": "trigger_pipeline",
            "arguments": {
              "repo": "$CLAUDE_PROJECT_DIR",
              "changed_file": "$CLAUDE_FILE_PATH"
            }
          }
        ]
      }
    ]
  }
}

The MCP tool is invoked on the specified server with the given arguments. Environment variable substitution works in argument values, letting you pass dynamic context from the event into the MCP call.

Security Considerations#

• Subprocess isolation: Command hooks run in a subprocess with a scrubbed environment. Sensitive variables like API_KEY are stripped unless explicitly allowlisted. Never hardcode secrets in hook commands — use environment variables or secret managers.
• Exit code semantics: Exit 0 = continue, exit 2 = block, exit 1 = error (logged but non-blocking). Any other exit code is treated as an error.
• Managed hooks: Enterprise deployments can set allowManagedHooksOnly: true in managed policy. This disables all user- and project-level hooks, ensuring only admin-approved hooks run. Use this when compliance requires strict control over automated actions.
• HTTP hook secrets: For HTTP hooks, store tokens in environment variables, not in the settings JSON. The settings file may be committed to version control.
• Input validation: Hook commands receive tool input via CLAUDE_TOOL_INPUT. Always validate and sanitize this data before using it in shell commands to prevent injection attacks. Prefer jq for parsing JSON input over raw string interpolation.
• Ordering matters: Hooks within a group run sequentially. If one blocks (exit 2), subsequent hooks in the same group are skipped. Plan your hook order accordingly.

Hooks are a powerful mechanism for keeping Claude Code aligned with your team's standards. Start with a simple auto-format or audit hook, then layer in guards and integrations as your workflow matures.