Hooks

Hooks let you run your own code at key points during a Claude Code session. You can use hooks to log tool usage, send notifications, enforce policies, block dangerous commands, or integrate with external systems — all without modifying Claude’s behavior directly.

How hooks work

A hook is a command (or HTTP request, or LLM prompt) associated with a lifecycle event. When the event fires, Claude Code runs your hook and optionally uses its output to influence behavior. For example:

A PreToolUse hook can block a Bash command before it runs by exiting with code 2
A PostToolUse hook can log every file write to an audit trail
A Notification hook can send a desktop notification when Claude finishes working
A Stop hook can verify that tests pass before Claude completes a task

Hook events

The following events are available:

Event	When it fires
`PreToolUse`	Before Claude runs any tool. Can block the tool by returning a non-zero exit code
`PostToolUse`	After a tool succeeds
`PostToolUseFailure`	After a tool fails
`Notification`	When Claude Code emits a notification (for example, task complete or waiting for input)
`UserPromptSubmit`	When you submit a message to Claude
`SessionStart`	When a session begins
`SessionEnd`	When a session ends
`Stop`	When Claude finishes a response. Can block completion by exiting with code 2
`StopFailure`	When a Stop hook blocks completion and Claude retries
`SubagentStart`	When a subagent (background task) starts
`SubagentStop`	When a subagent completes
`PreCompact`	Before context compaction runs
`PostCompact`	After context compaction completes
`PermissionRequest`	When Claude needs permission to use a tool (headless/async agents only)
`PermissionDenied`	When a tool use is denied
`Setup`	On Claude Code startup, before the session begins
`TeammateIdle`	When a teammate agent becomes idle
`TaskCreated`	When a background task is created
`TaskCompleted`	When a background task completes
`Elicitation`	When Claude requests additional information from the user
`ElicitationResult`	After an elicitation request is answered
`ConfigChange`	When settings change during a session
`WorktreeCreate`	When a git worktree is created
`WorktreeRemove`	When a git worktree is removed
`InstructionsLoaded`	When CLAUDE.md instruction files are loaded
`CwdChanged`	When the working directory changes
`FileChanged`	When a file is modified on disk

Hook configuration

Hooks are configured under the hooks key in any settings file. The structure is:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "optional-pattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ]
  }
}

Each event maps to an array of matchers. A matcher groups one or more hook commands under an optional pattern. The matcher field uses the same permission rule syntax as tool rules — for example, "Bash(git *)" matches only Bash commands that start with git.

Hook types

Command hook

Runs a shell command. This is the most common hook type.

{
  "type": "command",
  "command": "bash /path/to/my-script.sh"
}

type

"command"

required

Must be "command".

command

string

required

Shell command to execute. Runs via your default shell (bash unless overridden by the shell field).

shell

"bash" | "powershell"

Shell interpreter. Defaults to bash.

string

Permission rule syntax to filter when this hook runs, for example "Bash(git *)". Only runs if the tool call matches the pattern. Evaluated before spawning the process.

timeout

number

Timeout in seconds for this specific command. Overrides the global hook timeout.

statusMessage

string

Custom message to show in the spinner while the hook is running.

async

boolean

When true, the hook runs in the background without blocking Claude’s response.

once

boolean

When true, the hook runs once and is automatically removed after execution.

HTTP hook

POSTs the hook input as JSON to an HTTP endpoint.

{
  "type": "http",
  "url": "https://hooks.example.com/claude-events",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

type

"http"

required

Must be "http".

url

string

required

URL to POST the hook input JSON to.

headers

object

Additional HTTP headers. Values may reference environment variables using $VAR_NAME syntax. Only variables listed in allowedEnvVars are interpolated.

allowedEnvVars

string[]

Explicit list of environment variable names that may be interpolated into header values. Required for env var interpolation to work.

string

Permission rule syntax filter.

timeout

number

Timeout in seconds.

Prompt hook

Evaluates a prompt using a language model. The model’s response determines whether the hook allows or blocks the action.

{
  "type": "prompt",
  "prompt": "Verify that the following file write does not contain secrets: $ARGUMENTS"
}

type

"prompt"

required

Must be "prompt".

prompt

string

required

Prompt to evaluate. Use $ARGUMENTS as a placeholder for the hook input JSON.

model

string

Model to use for this prompt hook. Defaults to a small fast model.

string

Permission rule syntax filter.

timeout

number

Timeout in seconds.

Agent hook

Runs an agentic verification using a multi-turn LLM query. The agent must call a structured output tool with { "ok": true } or { "ok": false, "reason": "..." }.

{
  "type": "agent",
  "prompt": "Verify that unit tests ran and all passed. Check the output of the last Bash tool use."
}

type

"agent"

required

Must be "agent".

prompt

string

required

Prompt describing what to verify. Use $ARGUMENTS placeholder for hook input JSON.

model

string

Model to use. Defaults to Haiku.

timeout

number

Timeout in seconds. Defaults to 60.

Hook input and output

Input

Claude Code passes context to your hook via stdin as a JSON object. The shape varies by event, but always includes:

{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "git commit -m 'fix: update config'"
  }
}

For PostToolUse, the input also includes the tool output:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/tmp/output.txt",
    "content": "hello"
  },
  "tool_response": "File written successfully"
}

Output and exit codes

Your hook communicates back to Claude Code via stdout (for structured output) and exit code:

Exit code	Meaning for `PreToolUse`	Meaning for `Stop`
`0`	Allow the tool to run	Allow completion
`2`	Block the tool; show stdout to Claude as an error	Block completion; Claude retries with stdout as feedback
other	Error; tool runs anyway (non-blocking)	Non-blocking error

When a PreToolUse hook exits with code 2, the stdout is sent back to Claude as the tool error message. Claude then decides how to proceed based on that message.

Using `/hooks` to configure hooks

Run /hooks in a Claude Code session to open the hooks management panel. From there you can:

View all configured hooks grouped by event and source
Add new hooks interactively
Remove hooks you no longer want

Example: logging all tool uses

This hook appends every tool use to a log file:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{event: .hook_event_name, tool: .tool_name, time: now | todate}' >> ~/.claude/tool-log.jsonl"
          }
        ]
      }
    ]
  }
}

Example: blocking dangerous Bash commands

This hook blocks rm -rf commands before they run:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.command' | grep -q 'rm -rf'; then echo 'Blocked: rm -rf is not allowed'; exit 2; fi"
          }
        ]
      }
    ]
  }
}

The full hook input JSON is available as stdin, not as $CLAUDE_TOOL_INPUT. Read it with cat or pipe from stdin: read -r input; echo \"$input\" | jq -r '.tool_input.command'.

A cleaner version using stdin:

#!/usr/bin/env bash
# hooks/check-bash.sh
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // empty')

if [[ "$command" == *"rm -rf"* ]]; then
  echo "Blocked: rm -rf commands are not allowed in this project."
  exit 2
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/check-bash.sh"
          }
        ]
      }
    ]
  }
}

Example: desktop notification when Claude finishes

This hook sends a desktop notification when Claude completes a response (macOS):

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'",
            "async": true
          }
        ]
      }
    ]
  }
}

For Linux with notify-send:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude finished'",
            "async": true
          }
        ]
      }
    ]
  }
}

Example: verify tests pass before completing

This agent hook verifies that the previous Bash command ran tests and all passed:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Check the conversation transcript. If Claude just ran tests, verify that all tests passed. If any tests failed, return ok: false with the failure summary. If no tests were run, return ok: true.",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Hook sources and precedence

Hooks are collected from multiple sources and merged:

Source	File	Display name
User settings	`~/.claude/settings.json`	User
Project settings	`.claude/settings.json`	Project
Local settings	`.claude/settings.local.json`	Local
Managed settings	Platform-specific managed path	Managed

All hooks from all sources run for each event, in source precedence order (local → project → user → managed).

Disabling hooks

To disable all hooks for a session or project, set disableAllHooks: true in your settings:

{
  "disableAllHooks": true
}

Enterprise administrators can restrict hooks to managed settings only:

{
  "allowManagedHooksOnly": true
}

When allowManagedHooksOnly is set in managed settings, only hooks defined in the managed settings file are run. User, project, and local hooks are ignored.

Enterprise HTTP hook controls

Administrators can restrict which URLs HTTP hooks may target:

{
  "allowedHttpHookUrls": [
    "https://hooks.example.com/*",
    "https://audit.internal.company.com/claude-events"
  ],
  "httpHookAllowedEnvVars": ["AUTH_TOKEN", "TENANT_ID"]
}

allowedHttpHookUrls — only HTTP hooks targeting matching URLs are permitted. Supports * as a wildcard. If set to an empty array, no HTTP hooks are allowed.
httpHookAllowedEnvVars — allowlist of environment variable names that HTTP hooks may interpolate into headers. If set, a hook’s effective allowedEnvVars is restricted to the intersection with this list.

Get Started

Core Concepts

Configuration

Guides

Reference

How hooks work

Hook events

Hook configuration

Hook types

Command hook

HTTP hook

Prompt hook

Agent hook

Hook input and output

Input

Output and exit codes

Using `/hooks` to configure hooks

Example: logging all tool uses

Example: blocking dangerous Bash commands

Example: desktop notification when Claude finishes

Example: verify tests pass before completing

Hook sources and precedence

Disabling hooks

Enterprise HTTP hook controls

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Reference

Documentation Index

​How hooks work

​Hook events

​Hook configuration

​Hook types

​Command hook

​HTTP hook

​Prompt hook

​Agent hook

​Hook input and output

​Input

​Output and exit codes

​Using /hooks to configure hooks

​Example: logging all tool uses

​Example: blocking dangerous Bash commands

​Example: desktop notification when Claude finishes

​Example: verify tests pass before completing

​Hook sources and precedence

​Disabling hooks

​Enterprise HTTP hook controls

Build docs developers (and LLMs) love

How hooks work

Hook events

Hook configuration

Hook types

Command hook

HTTP hook

Prompt hook

Agent hook

Hook input and output

Input

Output and exit codes

Using `/hooks` to configure hooks

Example: logging all tool uses

Example: blocking dangerous Bash commands

Example: desktop notification when Claude finishes

Example: verify tests pass before completing

Hook sources and precedence

Disabling hooks

Enterprise HTTP hook controls