Claude Code hooks: how to set up your first hook, step by step

Before you start

You need Claude Code from lesson 1 and a settings file you can edit. The first hook sends a desktop notification, so it suits a machine with a desktop. The second hook is a Bash script that calls jq, which Anthropic's hooks guide installs with brew install jq on macOS or apt-get install jq on Debian and Ubuntu.

One rule applies to every hook you write. Anthropic's reference warns about what they can reach.

Set up your first hook: a notification when Claude needs you

Anthropic's own walkthrough starts with a notification, so you do not have to watch the terminal while Claude waits. The block below is the macOS version. It uses the Notification event, which fires when Claude is waiting for your input or permission.

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

1. Open ~/.claude/settings.json, creating it if it does not exist, and add the block above. On Linux, use notify-send 'Claude Code' 'Claude Code needs your attention' as the command. On Windows, copy the PowerShell command from the Windows tab of the hooks guide.
2. If the file already has a hooks key, add Notification next to the event names that are there. Each event is a key inside the one hooks object, so do not replace the whole object.
3. Save, then type /hooks at the Claude Code prompt. Your hook shows up in the list under Notification.
4. Press Esc to go back to the prompt. Press Shift+Tab until the status bar shows ⏸ manual mode on, ask Claude to do something that needs permission, then switch to another window. A desktop notification should arrive. Manual mode matters here because in auto mode a classifier reviews actions instead of asking you (lesson 2).

Events, matchers and where a hook lives

A hook has three layers, as the reference describes. First an event, like PreToolUse or Stop. Then a matcher group that filters when it fires, like "only for the Bash tool". Then the handler, which is the shell command. Your first hook used the empty matcher "", which fires on every notification type. Setting it to permission_prompt would fire it only when Claude needs approval, after the prompt has waited about six seconds.

For tool events the matcher is a tool name. Bash matches the Bash tool, and Edit|Write matches either of two tools. The guide says matchers are case-sensitive and must match the tool name exactly.

Where you save the block decides who gets the hook.

• ~/.claude/settings.json: all your projects, and not shared with anyone.
• .claude/settings.json: one project, and it can be committed so the team gets it too.
• .claude/settings.local.json: one project, and not committed.
• A plugin's hooks/hooks.json, or a skill's frontmatter: the hook travels with that plugin or skill.

A hook that says no: protect files from edits

A notification only reports. A PreToolUse hook can stop the action. This script, from the guide, reads the file path Claude is about to edit and refuses .env, package-lock.json and anything under .git/. The message it prints to stderr goes back to Claude, so Claude can adjust.

It parses JSON with jq and exits 2 to block. Save it as .claude/hooks/protect-files.sh.

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

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

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

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

1. Make the script executable on macOS and Linux with chmod +x .claude/hooks/protect-files.sh. Claude Code cannot run a hook script that is not executable.
2. Register it in .claude/settings.json as a PreToolUse hook with the matcher Edit|Write. The command is "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh, written with escaped quotes inside the JSON string.
3. Ask Claude to add a comment to your .env file. Claude Code blocks the edit before it runs and passes the Blocked: message to Claude.

How a hook answers: exit codes and input

Claude Code sends the event as JSON on the hook's standard input. Every event carries fields like session_id and cwd, and each type adds its own. A PreToolUse hook for Bash sees the tool name and the command, as in the example below. That is why the script above reads .tool_input.file_path for an edit.

The hook answers with its exit code. Exit 0 from a PreToolUse hook is not an approval, because the tool call still goes through the normal permission flow. For a hook that must decide with more detail, Claude Code also reads a JSON object from stdout when you exit 0. Pick one approach per hook, exit 2 or JSON, and do not mix them.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

How Claude Code's creator uses a format hook and notifications

Boris Cherny created Claude Code at Anthropic. His January 2026 setup thread on X says his team formats Claude's code with a PostToolUse hook. Claude usually writes well-formatted code, and the hook fixes the rest before a CI check fails on it. The auto-format hook in "Try it yourself" below is the same idea: PostToolUse, the matcher Edit|Write and Prettier.

The first tip in that thread is about waiting. He runs five Claude sessions at once in numbered terminal tabs and relies on system notifications to learn when one needs input. Your first hook in this lesson gives you that signal in any terminal, and the permission_prompt matcher narrows it to approval requests.

Screenshots of X's own embeds of the posts, taken on 5 November 2026, with the time in UTC. Select a screenshot to open the post on X.

Common mistakes

• A matcher that does not match. Matchers are case-sensitive and compare against the tool name, not the words in your prompt. Check the spelling, then check /hooks to see the hook under the event you meant.
• Replacing the hooks object instead of adding to it. Each event name is a sibling key inside the one hooks object.
• Invalid JSON in the settings file. Trailing commas and comments are not allowed, and a broken file leaves /hooks with nothing configured. Edits are normally picked up on their own. If a few seconds pass and nothing appears, restart the session.
• A script that is not executable, or one that cannot be found. Run chmod +x on it and point to it with $CLAUDE_PROJECT_DIR. If the transcript says jq: command not found, install jq.
• Expecting a successful hook to say something. It shows nothing, so check its effect, like a reformatted file, or press Ctrl+O to open the transcript view.
• Expecting PostToolUse to undo anything. The tool has already run. A formatter hook with the matcher Edit|Write also misses files that a Bash command rewrites.

Try it yourself

• Change the notification hook's matcher to permission_prompt and repeat the test. Then set it back to "" and compare when each one fires.
• Test the protect script by hand before you trust it: echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protect-files.sh, then echo $?. You should see the Blocked line and a 2.
• Open /hooks and select All events at the end of the list, to browse every event, including the ones with no hook.
• Add the guide's auto-format hook to .claude/settings.json. It is a PostToolUse hook with the matcher Edit|Write that runs Prettier on the edited file, and it needs jq and Prettier. Ask Claude to add single-quoted strings to a JavaScript file, then open the file.

Next: Agent Skills

That is the Claude Code course: install, plan mode, slash commands and hooks. The next course, Agent Skills, goes deeper on the SKILL.md format behind the commands you wrote in lesson 3.

Hooks also travel inside plugins, which our plugins guide covers. A project's standing instructions still belong in a CLAUDE.md file, because a hook enforces and a CLAUDE.md file explains.

Frequently asked questions

Sources

1. Claude Code docs: Automate actions with hooks (read November 4, 2026)https://code.claude.com/docs/en/hooks-guide
2. Claude Code docs: Hooks reference (read November 5, 2026)https://code.claude.com/docs/en/hooks
3. Boris Cherny on X: tip 9, a PostToolUse format hook, 2 January 2026 (read November 5, 2026)https://x.com/bcherny/status/2007179852047335529
4. Boris Cherny on X: tip 1, five sessions and notifications, 2 January 2026 (read November 5, 2026)https://x.com/bcherny/status/2007179833990885678