Hooks

Hooks let you attach custom logic to specific lifecycle events in Claude Code. When a hook event fires, Claude Code runs the configured command, evaluates a prompt, or spawns a sub-agent — before or after the triggering action takes place.

Hook events

Each hook is registered under one of the following events:

Event	When it fires
`PreToolUse`	Before a tool is invoked
`PostToolUse`	After a tool returns successfully
`PostToolUseFailure`	After a tool returns an error
`Notification`	When Claude Code sends a desktop notification
`UserPromptSubmit`	When the user submits a message
`SessionStart`	At the start of a new session
`SessionEnd`	When the session ends
`Stop`	When the agent finishes its response
`StopFailure`	When the agent stops due to an error
`SubagentStart`	When a sub-agent is spawned
`SubagentStop`	When a sub-agent finishes
`PreCompact`	Before context compaction
`PostCompact`	After context compaction
`PermissionRequest`	When a permission check is triggered
`PermissionDenied`	When a permission is denied
`Setup`	On `init` or `maintenance` trigger
`ConfigChange`	When settings change on disk
`InstructionsLoaded`	When a CLAUDE.md file is loaded
`CwdChanged`	When the working directory changes
`FileChanged`	When a watched file changes

Configuration

Hooks are defined in your settings JSON file (e.g. ~/.claude/settings.json for user-level hooks, or .claude/settings.json for project-level hooks) under the hooks key. The value is a map from event name to an array of matcher configurations.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to run Bash'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude finished'"
          }
        ]
      }
    ]
  }
}

Each matcher object has:

matcher (optional) — a string pattern matched against the tool name (e.g. "Bash", "Write")
hooks — an array of hook definitions to run when the matcher matches

The `if` condition

Every hook supports an if field that uses permission rule syntax to filter when the hook runs. The condition is evaluated against the hook input’s tool_name and tool_input fields.

{
  "type": "command",
  "command": "./scripts/lint.sh",
  "if": "Bash(git *)"
}

Only calls where the tool matches the pattern will trigger the hook. This avoids spawning hooks for non-matching commands. Examples:

"Bash(git *)" — any Bash call starting with git
"Read(*.ts)" — any Read call on a .ts file
"Write" — any Write call, regardless of path

Hook types

command — shell command

Runs a shell command. The hook input is passed as JSON via stdin.

{
  "type": "command",
  "command": "python3 ~/hooks/verify.py",
  "if": "Bash(git commit*)",
  "shell": "bash",
  "timeout": 30,
  "statusMessage": "Verifying commit...",
  "once": false,
  "async": false,
  "asyncRewake": false
}

Field	Type	Description
`command`	`string`	Shell command to execute
`if`	`string`	Permission rule filter (optional)
`shell`	`"bash"` \| `"powershell"`	Shell interpreter. Defaults to `bash` (uses `$SHELL`)
`timeout`	`number`	Timeout in seconds for this command
`statusMessage`	`string`	Custom spinner message while the hook runs
`once`	`boolean`	If `true`, the hook is removed after its first execution
`async`	`boolean`	If `true`, runs in the background without blocking the agent
`asyncRewake`	`boolean`	Runs in the background; wakes the model if exit code is `2` (implies `async`)

Exit code behaviour:

0 — success, continue normally
2 (with asyncRewake: true) — the model is woken and given the hook’s stdout as a new message
Any other non-zero — the hook is treated as an error

prompt — LLM evaluation

Sends a prompt to an LLM. Use $ARGUMENTS in the prompt string to inject the hook input JSON.

{
  "type": "prompt",
  "prompt": "Review the following tool input and check for secrets or credentials. Respond with 'BLOCK' if you find any, otherwise 'OK'. Input: $ARGUMENTS",
  "if": "Write",
  "model": "claude-sonnet-4-6",
  "timeout": 20,
  "statusMessage": "Checking for secrets...",
  "once": false
}

Field	Type	Description
`prompt`	`string`	Prompt to evaluate. Use `$ARGUMENTS` for hook input JSON
`if`	`string`	Permission rule filter (optional)
`model`	`string`	Model to use (e.g. `"claude-sonnet-4-6"`). Defaults to the small fast model
`timeout`	`number`	Timeout in seconds
`statusMessage`	`string`	Custom spinner message
`once`	`boolean`	If `true`, removed after first execution

agent — sub-agent verifier

Spawns a sub-agent to verify or act on the hook event. The agent receives a prompt describing what to check, with $ARGUMENTS replaced by the hook input JSON.

{
  "type": "agent",
  "prompt": "Verify that unit tests ran and passed before this commit. $ARGUMENTS",
  "if": "Bash(git commit*)",
  "model": "claude-sonnet-4-6",
  "timeout": 60,
  "statusMessage": "Running verification agent...",
  "once": false
}

Field	Type	Description
`prompt`	`string`	Verification prompt. Use `$ARGUMENTS` for hook input JSON
`if`	`string`	Permission rule filter (optional)
`model`	`string`	Model for the agent (e.g. `"claude-sonnet-4-6"`). Defaults to Haiku
`timeout`	`number`	Timeout in seconds (default 60)
`statusMessage`	`string`	Custom spinner message
`once`	`boolean`	If `true`, removed after first execution

http — HTTP webhook

POSTs the hook input JSON to a URL. Useful for integrating with external systems or webhooks.

{
  "type": "http",
  "url": "https://hooks.example.com/claude-event",
  "if": "PostToolUse",
  "timeout": 10,
  "headers": {
    "Authorization": "Bearer $MY_TOKEN",
    "Content-Type": "application/json"
  },
  "allowedEnvVars": ["MY_TOKEN"],
  "statusMessage": "Notifying webhook...",
  "once": false
}

Field	Type	Description
`url`	`string`	URL to POST the hook input JSON to
`if`	`string`	Permission rule filter (optional)
`timeout`	`number`	Timeout in seconds
`headers`	`Record<string, string>`	Additional HTTP headers. Values can reference env vars using `$VAR_NAME`
`allowedEnvVars`	`string[]`	Env var names allowed to be interpolated in header values
`statusMessage`	`string`	Custom spinner message
`once`	`boolean`	If `true`, removed after first execution

Background execution

By default hooks run synchronously and block the agent until they complete. Use async to run a hook in the background:

{
  "type": "command",
  "command": "~/scripts/log-tool-use.sh",
  "async": true
}

If you also want the background hook to be able to wake the model — for example to report a problem discovered asynchronously — use asyncRewake:

{
  "type": "command",
  "command": "~/scripts/monitor.sh",
  "asyncRewake": true
}

When the command exits with code 2, Claude Code treats the stdout as a new user message and resumes the model. Any other exit code is treated as normal background completion.

Full example

The following settings configuration uses all four hook types across multiple events:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[hook] PreToolUse Bash' >> /tmp/claude-hooks.log",
            "async": true
          },
          {
            "type": "prompt",
            "prompt": "Check the following Bash command for dangerous operations like rm -rf or curl | sh. Say BLOCK if it should be blocked, otherwise OK. Command: $ARGUMENTS",
            "if": "Bash",
            "statusMessage": "Safety checking command..."
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify the file being written does not contain hardcoded API keys or passwords. $ARGUMENTS",
            "statusMessage": "Scanning for credentials..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.example.com/post-tool",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'",
            "async": true
          }
        ]
      }
    ]
  }
}

Hook scripts receive the full hook input as JSON on stdin. For PreToolUse and PostToolUse events this includes tool_name, tool_input, session_id, transcript_path, and cwd.

Get Started

Core Concepts

Guides

Advanced

Hook events

Configuration

The `if` condition

Hook types

Background execution

Full example

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Hook events

​Configuration

​The if condition

​Hook types

​Background execution

​Full example

Build docs developers (and LLMs) love

Hook events

Configuration

The `if` condition

Hook types

Background execution

Full example