Automate workflows with hooks

Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.

Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them. Use hooks to enforce project rules, automate repetitive tasks, and integrate Claude Code with your existing tools.

For decisions that require judgment rather than deterministic rules, you can also use prompt-based hooks or agent-based hooks that use a Claude model to evaluate conditions.

For other ways to extend Claude Code, see skills for giving Claude additional instructions and executable commands, subagents for running tasks in isolated contexts, and plugins for packaging extensions to share across projects.

TIP

This guide covers common use cases and how to get started. For full event schemas, JSON input/output formats, and advanced features like async hooks and MCP tool hooks, see the Hooks reference.

Set up your first hook

To create a hook, add a hooks block to a settings file. This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.

1. Add the hook to your settings

Open ~/.claude/settings.json and add a Notification hook. The example below uses osascript for macOS; see Get notified when Claude needs input for Linux and Windows commands.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

If your settings file already has a hooks key, merge the Notification entry into it rather than replacing the whole object. You can also ask Claude to write the hook for you by describing what you want in the CLI.

2. Verify the configuration

Type /hooks to open the hooks browser. You'll see a list of all available hook events, with a count next to each event that has hooks configured. Select Notification to confirm your new hook appears in the list. Selecting the hook shows its details: the event, matcher, type, source file, and command.

3. Test the hook

Press Esc to return to the CLI. Ask Claude to do something that requires permission, then switch away from the terminal. You should receive a desktop notification.

TIP

The /hooks menu is read-only. To add, modify, or remove hooks, edit your settings JSON directly or ask Claude to make the change.

What you can automate

Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the Hooks reference.

Each example includes a ready-to-use configuration block that you add to a settings file. The most common patterns:

• Get notified when Claude needs input
• Auto-format code after edits
• Block edits to protected files
• Re-inject context after compaction
• Audit configuration changes
• Reload environment when directory or files change
• Auto-approve specific permission prompts

Get notified when Claude needs input

Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.

This hook uses the Notification event, which fires when Claude is waiting for input or permission. Each tab below uses the platform's native notification command. Add this to ~/.claude/settings.json:

macOS

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

If no notification appears

osascript routes notifications through the built-in Script Editor app. If Script Editor doesn't have notification permission, the command fails silently, and macOS won't prompt you to grant it. Run this in Terminal once to make Script Editor appear in your notification settings:

osascript -e 'display notification "test"'

Nothing will appear yet. Open System Settings > Notifications, find Script Editor in the list, and turn on Allow Notifications. Run the command again to confirm the test notification appears.

Linux

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Windows (PowerShell)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

Auto-format code after edits

Automatically run Prettier on every file Claude edits, so formatting stays consistent without manual intervention.

This hook uses the PostToolUse event with an Edit|Write matcher, so it runs only after file-editing tools. The command extracts the edited file path with jq and passes it to Prettier. Add this to .claude/settings.json in your project root:

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

INFO

The Bash examples on this page use jq for JSON parsing. Install it with brew install jq (macOS), apt-get install jq (Debian/Ubuntu), or see jq downloads.

Block edits to protected files

Prevent Claude from modifying sensitive files like .env, package-lock.json, or anything in .git/. Claude receives feedback explaining why the edit was blocked, so it can adjust its approach.

This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.

1. Create the hook script

Save this to .claude/hooks/protect-files.sh:

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

2. Make the script executable (macOS/Linux)

Hook scripts must be executable for Claude Code to run them:

chmod +x .claude/hooks/protect-files.sh

3. Register the hook

Add a PreToolUse hook to .claude/settings.json that runs the script before any Edit or Write tool call:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Re-inject context after compaction

When Claude's context window fills up, compaction summarizes the conversation to free space. This can lose important details. Use a SessionStart hook with a compact matcher to re-inject critical context after every compaction.

Any text your command writes to stdout is added to Claude's context. This example reminds Claude of project conventions and recent work. Add this to .claude/settings.json in your project root:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

You can replace the echo with any command that produces dynamic output, like git log --oneline -5 to show recent commits. For injecting context on every session start, consider using CLAUDE.md instead. For environment variables, see CLAUDE_ENV_FILE in the reference.

Audit configuration changes

Track when settings or skills files change during a session. The ConfigChange event fires when an external process or editor modifies a configuration file, so you can log changes for compliance or block unauthorized modifications.

This example appends each change to an audit log. Add this to ~/.claude/settings.json:

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

The matcher filters by configuration type: user_settings, project_settings, local_settings, policy_settings, or skills. To block a change from taking effect, exit with code 2 or return {"decision": "block"}. See the ConfigChange reference for the full input schema.

Reload environment when directory or files change

Some projects set different environment variables depending on which directory you are in. Tools like direnv do this automatically in your shell, but Claude's Bash tool does not pick up those changes on its own.

A CwdChanged hook fixes this: it runs each time Claude changes directory, so you can reload the correct variables for the new location. The hook writes the updated values to CLAUDE_ENV_FILE, which Claude Code applies before each Bash command. Add this to ~/.claude/settings.json:

{
  "hooks": {
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

To react to specific files instead of every directory change, use FileChanged with a matcher listing the filenames to watch (pipe-separated). The matcher both configures which files to watch and filters which hooks run. This example watches .envrc and .env for changes in the current directory:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

See the CwdChanged and FileChanged reference entries for input schemas, watchPaths output, and CLAUDE_ENV_FILE details.

Auto-approve specific permission prompts

Skip the approval dialog for tool calls you always allow. This example auto-approves ExitPlanMode, the tool Claude calls when it finishes presenting a plan and asks to proceed, so you aren't prompted every time a plan is ready.

Unlike the exit-code examples above, auto-approval requires your hook to write a JSON decision to stdout. A PermissionRequest hook fires when Claude Code is about to show a permission dialog, and returning "behavior": "allow" answers it on your behalf.

The matcher scopes the hook to ExitPlanMode only, so no other prompts are affected. Add this to ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

When the hook approves, Claude Code exits plan mode and restores whatever permission mode was active before you entered plan mode. The transcript shows "Allowed by PermissionRequest hook" where the dialog would have appeared. The hook path always keeps the current conversation: it cannot clear context and start a fresh implementation session the way the dialog can.

To set a specific permission mode instead, your hook's output can include an updatedPermissions array with a setMode entry. The mode value is any permission mode like default, acceptEdits, or bypassPermissions, and destination: "session" applies it for the current session only.

To switch the session to acceptEdits, your hook writes this JSON to stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [

      ]
    }
  }
}

Keep the matcher as narrow as possible. Matching on .* or leaving the matcher empty would auto-approve every permission prompt, including file writes and shell commands. See the PermissionRequest reference for the full set of decision fields.

How hooks work

Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:

Event	When it fires
SessionStart	When a session begins or resumes
UserPromptSubmit	When you submit a prompt, before Claude processes it
PreToolUse	Before a tool call executes. Can block it
PermissionRequest	When a permission dialog appears
PostToolUse	After a tool call succeeds
PostToolUseFailure	After a tool call fails
Notification	When Claude Code sends a notification
SubagentStart	When a subagent is spawned
SubagentStop	When a subagent finishes
TaskCreated	When a task is being created via TaskCreate
TaskCompleted	When a task is being marked as completed
Stop	When Claude finishes responding
StopFailure	When the turn ends due to an API error. Output and exit code are ignored
TeammateIdle	When an agent team teammate is about to go idle
InstructionsLoaded	When a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded during a session
ConfigChange	When a configuration file changes during a session
CwdChanged	When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv
FileChanged	When a watched file changes on disk. The matcher field specifies which filenames to watch
WorktreeCreate	When a worktree is being created via --worktree or isolation: "worktree". Replaces default git behavior
WorktreeRemove	When a worktree is being removed, either at session exit or when a subagent finishes
PreCompact	Before context compaction
PostCompact	After context compaction completes
Elicitation	When an MCP server requests user input during a tool call
ElicitationResult	After a user responds to an MCP elicitation, before the response is sent back to the server
SessionEnd	When a session terminates

Each hook has a type that determines how it runs. Most hooks use "type": "command", which runs a shell command. Three other types are available:

• "type": "http": POST event data to a URL. See HTTP hooks.
• "type": "prompt": single-turn LLM evaluation. See Prompt-based hooks.
• "type": "agent": multi-turn verification with tool access. See Agent-based hooks.

Read input and return output

Hooks communicate with Claude Code through stdin, stdout, stderr, and exit codes. When an event fires, Claude Code passes event-specific data as JSON to your script's stdin. Your script reads that data, does its work, and tells Claude Code what to do next via the exit code.

Hook input

Every event includes common fields like session_id and cwd, but each event type adds different data. For example, when Claude runs a Bash command, a PreToolUse hook receives something like this on stdin:

{
  "session_id": "abc123",          // unique ID for this session
  "cwd": "/Users/sarah/myproject", // working directory when the event fired
  "hook_event_name": "PreToolUse", // which event triggered this hook
  "tool_name": "Bash",             // the tool Claude is about to use
  "tool_input": {                  // the arguments Claude passed to the tool
    "command": "npm test"          // for Bash, this is the shell command
  }
}

Your script can parse that JSON and act on any of those fields. UserPromptSubmit hooks get the prompt text instead, SessionStart hooks get the source (startup, resume, clear, compact), and so on. See Common input fields in the reference for shared fields, and each event's section for event-specific schemas.

Hook output

Your script tells Claude Code what to do next by writing to stdout or stderr and exiting with a specific code. For example, a PreToolUse hook that wants to block a command:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2                                               # exit 2 = block the action
fi

exit 0  # exit 0 = let it proceed

The exit code determines what happens next:

• Exit 0: the action proceeds. For UserPromptSubmit and SessionStart hooks, anything you write to stdout is added to Claude's context.
• Exit 2: the action is blocked. Write a reason to stderr, and Claude receives it as feedback so it can adjust.
• Any other exit code: the action proceeds. Stderr is logged but not shown to Claude. Toggle verbose mode with Ctrl+O to see these messages in the transcript.

Structured JSON output

Exit codes give you two options: allow or block. For more control, exit 0 and print a JSON object to stdout instead.

INFO

Use exit 2 to block with a stderr message, or exit 0 with JSON for structured control. Don't mix them: Claude Code ignores JSON when you exit 2.

For example, a PreToolUse hook can deny a tool call and tell Claude why, or escalate it to the user for approval:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

Claude Code reads permissionDecision and cancels the tool call, then feeds permissionDecisionReason back to Claude as feedback. These three options are specific to PreToolUse:

• "allow": skip the interactive permission prompt. Deny and ask rules, including enterprise managed deny lists, still apply
• "deny": cancel the tool call and send the reason to Claude
• "ask": show the permission prompt to the user as normal

Returning "allow" skips the interactive prompt but does not override permission rules. If a deny rule matches the tool call, the call is blocked even when your hook returns "allow". If an ask rule matches, the user is still prompted. This means deny rules from any settings scope, including managed settings, always take precedence over hook approvals.

Other events use different decision patterns. For example, PostToolUse and Stop hooks use a top-level decision: "block" field, while PermissionRequest uses hookSpecificOutput.decision.behavior. See the summary table in the reference for a full breakdown by event.

For UserPromptSubmit hooks, use additionalContext instead to inject text into Claude's context. Prompt-based hooks (type: "prompt") handle output differently: see Prompt-based hooks.

Filter hooks with matchers

Without a matcher, a hook fires on every occurrence of its event. Matchers let you narrow that down. For example, if you want to run a formatter only after file edits (not after every tool call), add a matcher to your PostToolUse hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [

        ]
      }
    ]
  }
}

The "Edit|Write" matcher is a regex pattern that matches the tool name. The hook only fires when Claude uses the Edit or Write tool, not when it uses Bash, Read, or any other tool.

Each event type matches on a specific field. Matchers support exact strings and regex patterns:

Event	What the matcher filters	Example matcher values
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest	tool name	Bash, Edit|Write, mcp__.*
SessionStart	how the session started	startup, resume, clear, compact
SessionEnd	why the session ended	clear, resume, logout, prompt_input_exit, bypass_permissions_disabled, other
Notification	notification type	permission_prompt, idle_prompt, auth_success, elicitation_dialog
SubagentStart	agent type	Bash, Explore, Plan, or custom agent names
PreCompact, PostCompact	what triggered compaction	manual, auto
SubagentStop	agent type	same values as SubagentStart
ConfigChange	configuration source	user_settings, project_settings, local_settings, policy_settings, skills
StopFailure	error type	rate_limit, authentication_failed, billing_error, invalid_request, server_error, max_output_tokens, unknown
InstructionsLoaded	load reason	session_start, nested_traversal, path_glob_match, include, compact
Elicitation	MCP server name	your configured MCP server names
ElicitationResult	MCP server name	same values as Elicitation
FileChanged	filename (basename of the changed file)	.envrc, .env, any filename you want to watch
UserPromptSubmit, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged	no matcher support	always fires on every occurrence

A few more examples showing matchers on different event types:

Log every Bash command

Match only Bash tool calls and log each command to a file. The PostToolUse event fires after the command completes, so tool_input.command contains what ran. The hook receives the event data as JSON on stdin, and jq -r '.tool_input.command' extracts just the command string, which >> appends to the log file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

Match MCP tools

MCP tools use a different naming convention than built-in tools: mcp__<server>__<tool>, where <server> is the MCP server name and <tool> is the tool it provides. For example, mcp__github__search_repositories or mcp__filesystem__read_file. Use a regex matcher to target all tools from a specific server, or match across servers with a pattern like mcp__.*__write.*. See Match MCP tools in the reference for the full list of examples.

The command below extracts the tool name from the hook's JSON input with jq and writes it to stderr, where it shows up in verbose mode (Ctrl+O):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

Clean up on session end

The SessionEnd event supports matchers on the reason the session ended. This hook only fires on clear (when you run /clear), not on normal exits:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

For full matcher syntax, see the Hooks reference.

Filter by tool name and arguments with the if field

INFO

The if field requires Claude Code v2.1.85 or later. Earlier versions ignore it and run the hook on every matched call.

The if field uses permission rule syntax to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches. This goes beyond matcher, which filters at the group level by tool name only.

For example, to run a hook only when Claude uses git commands rather than all Bash commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

The hook process only spawns when the Bash command starts with git. Other Bash commands skip this handler entirely. The if field accepts the same patterns as permission rules: "Bash(git *)", "Edit(*.ts)", and so on. To match multiple tool names, use separate handlers each with its own if value, or match at the matcher level where pipe alternation is supported.

if only works on tool events: PreToolUse, PostToolUse, PostToolUseFailure, and PermissionRequest. Adding it to any other event prevents the hook from running.

Configure hook location

Where you add a hook determines its scope:

Location	Scope	Shareable
~/.claude/settings.json	All your projects	No, local to your machine
.claude/settings.json	Single project	Yes, can be committed to the repo
.claude/settings.local.json	Single project	No, gitignored
Managed policy settings	Organization-wide	Yes, admin-controlled
Plugin hooks/hooks.json	When plugin is enabled	Yes, bundled with the plugin
Skill or agent frontmatter	While the skill or agent is active	Yes, defined in the component file

Run /hooks in Claude Code to browse all configured hooks grouped by event. To disable all hooks at once, set "disableAllHooks": true in your settings file.

If you edit settings files directly while Claude Code is running, the file watcher normally picks up hook changes automatically.

Prompt-based hooks

For decisions that require judgment rather than deterministic rules, use type: "prompt" hooks. Instead of running a shell command, Claude Code sends your prompt and the hook's input data to a Claude model (Haiku by default) to make the decision. You can specify a different model with the model field if you need more capability.

The model's only job is to return a yes/no decision as JSON:

• "ok": true: the action proceeds
• "ok": false: the action is blocked. The model's "reason" is fed back to Claude so it can adjust.

This example uses a Stop hook to ask the model whether all requested tasks are complete. If the model returns "ok": false, Claude keeps working and uses the reason as its next instruction:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

For full configuration options, see Prompt-based hooks in the reference.

Agent-based hooks

When verification requires inspecting files or running commands, use type: "agent" hooks. Unlike prompt hooks which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.

Agent hooks use the same "ok" / "reason" response format as prompt hooks, but with a longer default timeout of 60 seconds and up to 50 tool-use turns.

This example verifies that tests pass before allowing Claude to stop:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Use prompt hooks when the hook input data alone is enough to make a decision. Use agent hooks when you need to verify something against the actual state of the codebase.

For full configuration options, see Agent-based hooks in the reference.

HTTP hooks

Use type: "http" hooks to POST event data to an HTTP endpoint instead of running a shell command. The endpoint receives the same JSON that a command hook would receive on stdin, and returns results through the HTTP response body using the same JSON format.

HTTP hooks are useful when you want a web server, cloud function, or external service to handle hook logic: for example, a shared audit service that logs tool use events across a team.

This example posts every tool use to a local logging service:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

The endpoint should return a JSON response body using the same output format as command hooks. To block a tool call, return a 2xx response with the appropriate hookSpecificOutput fields. HTTP status codes alone cannot block actions.

Header values support environment variable interpolation using $VAR_NAME or ${VAR_NAME} syntax. Only variables listed in the allowedEnvVars array are resolved; all other $VAR references remain empty.

For full configuration options and response handling, see HTTP hooks in the reference.

Limitations and troubleshooting

Limitations

• Command hooks communicate through stdout, stderr, and exit codes only. They cannot trigger commands or tool calls directly. HTTP hooks communicate through the response body instead.
• Hook timeout is 10 minutes by default, configurable per hook with the timeout field (in seconds).
• PostToolUse hooks cannot undo actions since the tool has already executed.
• PermissionRequest hooks do not fire in non-interactive mode (-p). Use PreToolUse hooks for automated permission decisions.
• Stop hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts. API errors fire StopFailure instead.

Hook not firing

The hook is configured but never executes.

• Run /hooks and confirm the hook appears under the correct event
• Check that the matcher pattern matches the tool name exactly (matchers are case-sensitive)
• Verify you're triggering the right event type (e.g., PreToolUse fires before tool execution, PostToolUse fires after)
• If using PermissionRequest hooks in non-interactive mode (-p), switch to PreToolUse instead

Hook error in output

You see a message like "PreToolUse hook error: ..." in the transcript.

• Your script exited with a non-zero code unexpectedly. Test it manually by piping sample JSON:

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code

• If you see "command not found", use absolute paths or $CLAUDE_PROJECT_DIR to reference scripts
• If you see "jq: command not found", install jq or use Python/Node.js for JSON parsing
• If the script isn't running at all, make it executable: chmod +x ./my-hook.sh

/hooks shows no hooks configured

You edited a settings file but the hooks don't appear in the menu.

• File edits are normally picked up automatically. If they haven't appeared after a few seconds, the file watcher may have missed the change: restart your session to force a reload.
• Verify your JSON is valid (trailing commas and comments are not allowed)
• Confirm the settings file is in the correct location: .claude/settings.json for project hooks, ~/.claude/settings.json for global hooks

Stop hook runs forever

Claude keeps working in an infinite loop instead of stopping.

Your Stop hook script needs to check whether it already triggered a continuation. Parse the stop_hook_active field from the JSON input and exit early if it's true:

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

JSON validation failed

Claude Code shows a JSON parsing error even though your hook script outputs valid JSON.

When Claude Code runs a hook, it spawns a shell that sources your profile (~/.zshrc or ~/.bashrc). If your profile contains unconditional echo statements, that output gets prepended to your hook's JSON:

Shell ready on arm64

Claude Code tries to parse this as JSON and fails. To fix this, wrap echo statements in your shell profile so they only run in interactive shells:

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

The $- variable contains shell flags, and i means interactive. Hooks run in non-interactive shells, so the echo is skipped.

Debug techniques

Toggle verbose mode with Ctrl+O to see hook output in the transcript, or run claude --debug for full execution details including which hooks matched and their exit codes.

Learn more

• Hooks reference: full event schemas, JSON output format, async hooks, and MCP tool hooks
• Security considerations: review before deploying hooks in shared or production environments
• Bash command validator example: complete reference implementation