Claude Code hooks: a practical guide

A hook is a shell command registered in settings.json against a lifecycle event. When the event fires, Claude Code runs your command, pipes a JSON object describing the event to its stdin, and — for some events — reads JSON back from stdout to decide what to do next.

That's the whole model. It's small, and it's enough to build notifications, auto-formatting, audit logs, and policy guardrails without touching the agent itself.

The thirteen events

How to register one

Hooks live under the hooks key in any settings file. Each event maps to an array of matcher groups; each group has a matcher and a list of commands to run.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/notify.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

An empty matcher means *every* occurrence of that event. For tool events, the matcher is permission-rule syntax — the CLI describes it as: *Permission rule syntax to filter when this hook runs (e.g., "Bash(git *)"). Only runs if the tool call matches the pattern. Avoids spawning hooks for non-matching commands.* Use it. A hook that shells out on every single tool call is a real latency cost.

What your script receives

Every hook gets a JSON object on stdin. The fields that are always there:

• session_id — the session that triggered the event. This is your correlation key if you're tracking several agents.
• hook_event_name — which event fired, so one script can handle several registrations.
• cwd — the session's working directory. In a multi-project setup this is how you know *which* project needs you.
• transcript_path — path to the session transcript on disk.
• permission_mode — the mode the session is running in.

Tool events add tool_input (the arguments Claude wants to use) and, for PostToolUse, tool_response.

What your script can send back

Print a JSON object to stdout and Claude Code will act on it. Exit code 0 with no output means 'carry on'.

Example: tell me when an agent needs me

The single most useful hook if you run agents in the background. Notification fires when Claude Code wants your attention, including when it's been idle waiting on you.

#!/usr/bin/env bash
# ~/.claude/hooks/notify.sh
set -euo pipefail

payload=$(cat)
cwd=$(printf '%s' "$payload" | /usr/bin/python3 -c \
  'import json,sys; print(json.load(sys.stdin).get("cwd",""))')
project=$(basename "$cwd")

/usr/bin/osascript -e "display notification \"Needs a decision\" \
  with title \"Claude Code — $project\" sound name \"Ping\""

Make it executable (chmod +x) and register it against Notification. Note the absolute paths — hooks don't necessarily inherit the PATH from your interactive shell, and a hook that silently fails because python3 wasn't found is an annoying afternoon.

Example: format files after Claude edits them

#!/usr/bin/env bash
# ~/.claude/hooks/format.sh — register on PostToolUse, matcher "Edit"
set -euo pipefail

file=$(cat | /usr/bin/python3 -c \
  'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))')

case "$file" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.css)
    npx --no-install prettier --write "$file" >/dev/null 2>&1 || true
    ;;
esac

The || true matters. A hook that exits non-zero on a file Prettier doesn't understand will interrupt the session for no good reason.

Example: a hard guardrail

PreToolUse can deny a tool call outright, regardless of permission mode. This is a stronger guarantee than a deny rule, because you can express conditions that rule syntax can't — like 'never push while on main'.

#!/usr/bin/env bash
# ~/.claude/hooks/guard-push.sh
# Register on PreToolUse with matcher "Bash(git push *)"
set -euo pipefail

branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")

if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
  cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Direct pushes to the default branch are blocked. Open a PR."
  }
}
JSON
fi

Printing nothing means the call proceeds to normal permission handling. Printing the deny object stops it and hands Claude the reason, so it can adapt rather than retry blindly.

Debugging hooks

• claude --debug hooks filters debug output to hook execution — the fastest way to see whether your command ran at all.
• claude doctor checks the health of your installation and reads settings files without a trust prompt.
• Log the raw payload to a file first (tee /tmp/hook.json) before writing any parsing logic. The field names are easier to read than to remember.
• Use absolute paths for interpreters and binaries.
• Remember settings merge across user, project, and local scopes — a hook you can't find may be registered in a scope you're not looking at. --setting-sources controls which layers load.

Where hooks stop being enough

Hooks are excellent at *emitting* a signal and quite good at *enforcing* policy. What they can't do is guarantee the signal reaches you. PermissionRequest will fire reliably every time an agent blocks; whether you notice depends entirely on what the hook does next and where you happen to be looking.

That gap is exactly what BubbleCode was built to close — it registers SessionStart, SessionEnd, Stop, and PermissionRequest hooks plus a statusline to track sessions started from your terminal, then surfaces them in an overlay that renders above whatever you're doing.