Claude Code hooks: a practical guide with examples

What are Claude Code hooks?#

A hook is a handler that Claude Code runs when a lifecycle event fires. Most are shell commands, but a handler can also be an HTTP endpoint (http), a tool on an MCP server (mcp_tool), a one-shot question to a Claude model (prompt) or a subagent that checks files first (agent, still experimental).

The point is certainty. An instruction in CLAUDE.md is advice Claude usually follows; a hook runs every time its event fires, whatever Claude decides. Use CLAUDE.md for conventions, permission rules for plain allow and deny lists, and hooks for anything that needs a script.

Where do hooks go? The settings.json format#

Inside the file, hooks nest three levels deep: the event, a matcher group that filters it, and one or more handlers. Every matching handler runs, in parallel:

{
  "hooks": {
    "PreToolUse": [                    <- the event
      {
        "matcher": "Edit|Write",       <- which tools, sources or types
        "hooks": [                     <- one or more handlers
          { "type": "command", "command": "<shell command>" }
        ]
      }
    ],
    "Stop": [ ... ]                    <- more events sit beside it
  }
}

Claude Code picks up edits to settings files mid-session. Run /hooks to check: it’s a read-only list of every configured hook and the file it came from.

How matchers work

• Plain names: Bash matches only Bash; Edit|Write and Edit, Write match either. Matchers are case-sensitive.
• Anything with other characters is an unanchored JavaScript regex: Edit.* also matches NotebookEdit, so write ^Edit$ for an exact match.
• MCP tools are named mcp__<server>__<tool>. Match a whole server with mcp__github__.*; the .* is required.
• **"*", "" or no matcher** matches everything. Events without matcher support ignore the field.
• `if` narrows one handler on tool events with permission-rule syntax, such as "if": "Bash(git push *)". It’s best-effort, so don’t rely on it for security.

Every Claude Code hook event, and when it fires#

There are 33 hook events. SessionStart and SessionEnd fire once per session, UserPromptSubmit and Stop once per turn, and PreToolUse and PostToolUse around every tool call.

Exit codes and JSON output: how a hook talks back#

• Exit 0: success. Claude Code reads any JSON on stdout. Plain text goes to the debug log, except on UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch, where Claude gets it as context.
• Exit 2: a blocking error, with stderr as the reason. On PreToolUse the call is stopped and Claude reads why. Events that can’t block just show the message: to Claude after PostToolUse, to you after SessionStart.
• Anything else: a non-blocking error. The action goes ahead and the transcript shows a “hook error” notice.

For finer control, exit 0 and print one JSON object, and nothing else, to stdout. PreToolUse puts its decision inside hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use the staging database, not production"
  }
}

• `permissionDecision`: allow, deny, ask, or defer in -p mode. When hooks disagree, deny wins. An allow skips the prompt but never overrides a deny rule.
• `updatedInput` rewrites the tool’s arguments. It replaces the whole input, so include unchanged fields.
• `additionalContext` gives Claude a note beside the result. At the top level instead of inside hookSpecificOutput, it’s silently ignored.
• Other events such as PostToolUse and Stop use a top-level "decision": "block" plus reason; PermissionRequest uses decision.behavior.
• Universal fields: "continue": false stops Claude, systemMessage warns you and terminalSequence sends a desktop notification, though some events ignore the first two.

Injected context fills Claude’s context window, and each string is capped at 10,000 characters. Paste a sample into the token counter to see what a hook adds per turn.

7 Claude Code hook examples you can copy#

The Bash scripts need jq. Save them under .claude/hooks/ and chmod +x them on macOS and Linux. Merge the JSON into a single hooks object, one key per event.

1. Format every file Claude edits

Prettier runs after each Edit or Write; --ignore-unknown skips file types it can’t format instead of failing:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\""
          }
        ]
      }
    ]
  }
}

Don’t pipe the path through xargs, as some examples do: xargs strips backslashes, so on Windows C:\Users\…\src\a.js reached Prettier as C:Users…srca.js and failed with “No files matching the pattern were found”. The quoted form worked.

2. Block edits to protected files

This script exits 2 when Claude tries to edit .env files, anything in .git/ or secrets/, or the lockfile, and also when jq is missing, so it fails closed instead of letting every edit through. Claude reads the message and changes course:

#!/bin/bash
# .claude/hooks/protect-files.sh: block edits to protected paths. Exit 2 = block.
command -v jq >/dev/null || { echo "protect-files: jq is not installed" >&2; exit 2; }
input=$(cat)
file=$(jq -r '.tool_input.file_path // empty' <<<"$input")
file="${file//\\//}"   # Windows paths arrive with backslashes
shopt -s nocasematch     # .ENV and .env are the same file on Windows and macOS

case "$file" in
  */.env.example) ;;   # the template is fine to edit
  */.git/*|*/secrets/*|*/.env|*/.env.*|*/package-lock.json)
    echo "Blocked: $file is protected. Ask the user to change it by hand." >&2
    exit 2 ;;
esac
exit 0

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

Given a Windows path to .env, it printed Blocked: C:/project/.env is protected. and exited 2; .env.example and src/index.ts exited 0. It only sees Edit and Write: a shell command like echo KEY=1 >> .env bypasses it. To catch those, the docs suggest also matching Bash|PowerShell and checking git status --porcelain, or using a FileChanged hook.

3. Run the tests after edits

With "async": true the tests run in the background while Claude keeps working, and the result reaches Claude on its next turn:

#!/bin/bash
# .claude/hooks/run-tests.sh: run the tests after a source edit, tell Claude the result.
input=$(cat)
file=$(jq -r '.tool_input.file_path // empty' <<<"$input")
case "$file" in
  *.ts|*.tsx|*.js|*.jsx) ;;
  *) exit 0 ;;   # not a source file: nothing to do
esac

if out=$(npm test --silent 2>&1); then
  msg="Tests passed after editing $file."
else
  msg="Tests failed after editing $file. Last lines:
$(tail -n 30 <<<"$out")"
fi
jq -nc --arg msg "$msg" \
  '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Only the last 30 lines of a failure go back. An async hook can’t block; to stop Claude finishing until tests pass, run the check from a Stop hook that exits 2.

4. Get a notification when Claude is done

Stop fires whenever Claude finishes responding, and Notification with permission_prompt when an approval has waited about six seconds. The script returns a terminalSequence for Claude Code to emit: OSC 9 suits Windows Terminal, iTerm2, WezTerm and ConEmu; Ghostty, Warp and urxvt use OSC 777.

#!/bin/bash
# ~/.claude/hooks/notify.sh: ask the terminal for a desktop notification (OSC 9).
seq=$(printf '\033]9;%s\007' "${1:-Claude Code}")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME\"/.claude/hooks/notify.sh 'Claude Code finished'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME\"/.claude/hooks/notify.sh 'Claude Code needs your approval'"
          }
        ]
      }
    ]
  }
}

5. Keep an audit log of shell commands

Every command Claude tries to run, allowed or not, is appended to a JSON Lines file. It matches PowerShell too, because on Windows Claude may use the PowerShell tool:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: (now | todate), session: .session_id, cwd, tool: .tool_name, command: .tool_input.command}' >> ~/.claude/command-audit.jsonl"
          }
        ]
      }
    ]
  }
}

{"time":"2026-10-11T09:36:29Z","session":"abc123","cwd":"C:\\proj","tool":"Bash","command":"npm test"}
{"time":"2026-10-11T09:36:30Z","session":"abc123","cwd":"C:\\proj","tool":"PowerShell","command":"Get-ChildItem"}

6. Inject git context at session start

A SessionStart hook’s plain stdout becomes context. With no matcher it also runs after /clear, a resume and compaction, so the branch and recent commits stay current. Keep it fast: Claude’s first reply waits for it.

#!/bin/bash
# .claude/hooks/session-context.sh: plain stdout becomes context for Claude.
echo "Branch: $(git branch --show-current)"
echo "Uncommitted changes:"
git status --short | head -n 20
echo "Recent commits:"
git log --oneline -5

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-context.sh"
          }
        ]
      }
    ]
  }
}

7. Ask before every git push

No script needed. The if field narrows the handler to git push, and the JSON answer ask forces a confirmation prompt:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push *)",
            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"git push: check the branch and remote first\"}}'"
          }
        ]
      }
    ]
  }
}

Are Claude Code hooks safe?#

Hooks are as safe as the commands in them. Command hooks run with your full user permissions, so treat one in someone else’s repository like a script you’re about to run.

• Trust. Interactive sessions hold back settings-file hooks until you accept the workspace trust dialog. -p and SDK runs have no dialog, so hooks committed to a cloned repository run at once.
• Off switch. claude --settings '{"disableAllHooks": true}' turns off all but managed hooks for one run. To drop a single hook, delete its entry.
• Scripts. Quote variables ("$file"), use $CLAUDE_PROJECT_DIR instead of relative paths, and skip .env, .git/ and keys.
• One-way power. A hook’s deny blocks a call even in bypassPermissions mode, but its allow can’t override a deny rule. Admins can set allowManagedHooksOnly.

Claude Code hooks on Windows#

Hooks run in Git Bash when it’s installed, otherwise in PowerShell (this error means Claude Code found neither). Watch for:

• Backslash paths. file_path arrives as C:\project\src\index.ts even in Git Bash. Normalise it, as example 2 does, before matching /src/ or /.env.
• No jq. Git Bash lacks it: we got jq: command not found until winget install jqlang.jq.
• `Bash|PowerShell` matchers. Where the PowerShell tool is enabled, Claude routes shell commands through it, and a Bash-only hook never fires.
• `$env:CLAUDE_PROJECT_DIR` in PowerShell hooks; bare $CLAUDE_PROJECT_DIR is an empty local variable there. Git Bash runs #!/bin/bash scripts without chmod.

Without Git Bash, write the hook in PowerShell. This version of example 2 needs no jq and gave the same results in Windows PowerShell 5.1. Exec form (args) runs it with no shell quoting:

# .claude/hooks/protect-files.ps1: the same rule without Git Bash or jq. Exit 2 = block.
$hook = [Console]::In.ReadToEnd() | ConvertFrom-Json
$file = $hook.tool_input.file_path -replace '\\', '/'
if ($file -match '/\.env\.example$') { exit 0 }
if ($file -match '/(\.git|secrets)/|/\.env(\..+)?$|/package-lock\.json$') {
  [Console]::Error.WriteLine("Blocked: $file is protected. Ask the user to change it by hand.")
  exit 2
}
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.ps1"
            ]
          }
        ]
      }
    ]
  }
}

Debugging: why isn’t my hook running?#

First test the script alone: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?. Then use Claude Code’s tools: /hooks shows whether it loaded, Ctrl+O shows blocks and “hook error” notices in the transcript, and claude --debug logs every run to ~/.claude/debug/<session-id>.txt (not the terminal). --debug-file <path> picks the path; /debug starts logging mid-session.

Hooks that call MCP tools need the server configured first: the MCP config generator writes the entry and MCP servers in Claude Code covers connecting it. Checks that should run in their own context belong in Claude Code subagents, which can carry hooks too.