Where do Claude Code hooks go? File locations and scope

Every place a hook can live

What a hook looks like in settings.json

Add a hooks key at the top level. Each event name is a key inside that one object, so if the file already has a hooks key, add your event beside the existing ones rather than replacing the block. This one shows a Mac notification when Claude needs you and formats files after edits:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Where the hook script goes

The JSON has to be in a settings file, but the script it runs can be anywhere. The docs' examples keep project scripts in .claude/hooks/ and point at them with ${CLAUDE_PROJECT_DIR}, the project root where the session started:

"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh"

Use that form or an absolute path to avoid a command not found error, and make the script executable with chmod +x.

How the files combine

• Hooks add up. Hook entries merge across settings levels. User, project and local settings add their own without removing anyone else's, including managed ones.
• disableAllHooks follows normal precedence. A false in a project's .claude/settings.json overrides a true in your user settings. Only managed settings can turn off managed hooks.
• Trust comes first. In an interactive session, Claude Code holds back hooks from every settings file, your own included, until you accept the workspace trust dialog for the folder. A -p or SDK session never shows the dialog and treats the folder as trusted, so committed hooks run. Review a repo's .claude/ settings before scripting claude -p over code you didn't write.
• Cloud sessions don't read your local ~/.claude/settings.json.

Other settings resolve differently from hooks. See which settings.json wins for the rest.

Check that the hook loaded

1. Run /hooks. It lists every hook registered for the session, grouped by event.
2. If yours is missing, check that it's under the hooks key, that the JSON has no trailing commas or comments, and that matcher is a single string. An array there marks the entry invalid in claude doctor.
3. If it's listed but doesn't fire, check the matcher. Use | between tool names, as in "Edit|Write". Matchers are case-sensitive, and a misspelled tool name fails silently.
4. Start with claude --debug to see each event, the matchers checked, and the hook's exit code and output.

A hook defined in a skill's frontmatter doesn't show in /hooks until that skill has been invoked in the session.

When to use a hook

Use a hook for anything that must happen every time. CLAUDE.md instructions are context that Claude tries to follow; a hook runs as a command at a fixed point whatever Claude decides. See why Claude Code ignores CLAUDE.md for how to tell which one a rule needs.

Rulebook, the Mac app we are building, lists the hook events and matcher counts in each settings file and has a switch for disableAllHooks. Editing the hooks themselves happens in its raw JSON view.