Why is my Claude Code hook not running?

The usual cause is that the hook IS running and you cannot see it. A hook's stderr goes only to the debug log, never to the transcript, so a script that runs and fails looks identical to a script that never fired. Run claude --debug hooks and you will see hook resolution, the spawn, and any error. The second most common cause is the matcher: a plain tool name like Bash is an exact, case-sensitive match, not a glob.

Do I need to restart Claude Code after editing hooks?

No. Claude Code watches the settings files and picks up hook changes without a restart. If a hook still does not fire after an edit, the problem is the configuration itself rather than a stale session, so go to claude --debug hooks rather than restarting and hoping.

Is a Claude Code hook matcher a regex or a glob?

Neither, by default. "*", an empty string, or an omitted matcher matches every event of that type. A value made only of letters, digits, underscores, hyphens, spaces, commas and pipes is treated as an exact tool-name match, case-sensitive, and a pipe or comma separated list means any of those names. Only when the value contains other characters, such as a caret or a backslash, is it evaluated as an unanchored regular expression. Glob syntax is never used, so "Bash(*)" is not a valid matcher and matches no tool.

What exit code does a Claude Code hook use to block an action?

Exit 2. Exit 0 is success and exit 1 is a non-blocking error, which is the trap: the Unix habit of returning 1 on failure produces a hook that reports a problem and then lets the action through anyway. To actually stop a tool call, exit 2 and put the reason on stderr, or return JSON with the decision fields.

Where do Claude Code hooks get configured, and which file wins?

Hooks can be set in ~/.claude/settings.json for every project, .claude/settings.json for one project shared with the team, .claude/settings.local.json for one project just for you, a managed policy file set by an organisation, and inside a plugin's hooks/hooks.json. They merge rather than override, so a hook in the user file and a hook in the project file both run. That merge is why a hook you thought you removed can still fire from another level.

Why does my hook script work in the terminal but not as a hook?

Two differences bite. A hook runs with no controlling terminal, so anything that reads from the keyboard, opens /dev/tty, or prompts for input fails rather than asking. And the command form matters: with no args field the command goes through a shell, so pipes and redirects work, while the exec form bypasses the shell and a pipe in the string is then just a literal character.

Claude Code hooks are configured but never run

Nine times out of ten the hook is running. It just has no way to tell you it failed.

Last updated: 2026-09-21 · checked against Claude Code 2.1.278

The short answer

Most “my hook never runs” reports are a hook that does run and cannot tell you anything. A hook’s stderr goes to the debug log only — never to the transcript. So a script that fires and crashes on line one looks exactly like a script that was never wired up.

Before changing any configuration, make it speak:

claude --debug hooks

That prints hook resolution, which file each hook came from, the process spawn, and the error if there is one. In-session, /hooks lists what is actually loaded. If the hook is not in that list, it is a configuration problem. If it is in that list, it is a script problem, and those are two different afternoons.

The five causes, in the order they actually happen

#	Cause	How you tell
1	The hook runs and fails silently. stderr never reaches the transcript	`claude --debug hooks` shows the spawn and the error
2	The matcher does not match. A plain tool name is an exact, case-sensitive string, not a glob	`Edit` matches; `edit` and `Edit(*)` match nothing
3	The script exits `1` expecting to block	The action goes through anyway. Only exit 2 blocks
4	The script wants a terminal	Works when you run it by hand, dies as a hook
5	It is loaded under an event you did not mean	`/hooks` shows the event and the source file

Note what is not on this list: needing to restart. Claude Code watches the settings files, so an edit is picked up without restarting the session. If restarting appeared to fix it once, something else changed too.

The matcher is the one people get wrong

It is not a glob, and it is not always a regex. Three cases:

You write	It means
`"*"`, `""`, or no `matcher` key at all	Every event of that type
`"Edit"` or `"Edit\|Write"`	Exact tool names, case-sensitive. A pipe or comma separated list means any of them
`"mcp__.*"`	Because it contains regex characters, it is treated as an unanchored regular expression

So Edit(*) is not “Edit with any arguments”. It is a literal string that matches no tool at all. The Bash(npm test:*) shape you may be copying from is permission syntax for permissions.allow, which is a different mechanism with different rules — see Claude Code keeps asking permission.

A hook that formats the file that just changed

The shape, then the three details that decide whether it works:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/format.sh" }
        ]
      }
    ]
  }
}

The script must be executable and have a shebang. Without either it fails at spawn, and that failure is in the debug log, not on your screen.
It reads JSON on stdin — including tool_name, tool_input, cwd and session_id — not command-line arguments.
Exit 0 to allow, exit 2 to block. Anything else is a non-blocking error: you get a line in the log and the action proceeds.

Where hooks live, and why removing one is harder than adding one

Hooks can arrive from five places at once, and they merge rather than override:

File	Scope
`~/.claude/settings.json`	Every project you open
`.claude/settings.json`	This project, committed, shared with the team
`.claude/settings.local.json`	This project, just you, usually gitignored
A managed policy file	Set by an organisation, and not yours to disable
A plugin’s `hooks/hooks.json`	Whatever the plugin brought with it

Because they merge, deleting a hook from your project file does not stop it if the same hook also sits in your user file or arrived with a plugin. /hooks names the source file for each one, which is the fastest way to find the copy you forgot about.

If none of that is it

Put the output somewhere you will actually see it. stderr is invisible; a file is not:

claude --debug hooks --debug-file /tmp/cc-debug.log

Then tail -f /tmp/cc-debug.log in a second terminal and trigger the tool. If the hook never appears, it is not loaded, and the problem is in one of the five files above rather than in your script.

The free starter repo ships a PostToolUse formatter and a Stop reminder that both work, which is often a faster fix than debugging your own.

Free starter repo

Plugin, skill, subagent, MCP server or slash command — which is which
Claude Code keeps asking permission for the same command — a different file, a different mechanism
Claude Code forgets my project every session
My MCP server will not connect

What does it cost to have someone set this up?

Flat prices, written scope, stop at any rung. No call to book, no retainer.

Rung	What you get	Clock
Free — starter repo	A real setup you copy yourself	now
$29 — Setup Lite	One project: CLAUDE.md, allowlist, one skill, as a pull request you review	24 hours
$99 — Setup Sprint	3–5 skills, hooks, up to 3 MCP servers, plus a runbook	48 hours
$79 — Surface Audit	Already set up and still fighting it: contradictions and an exact fix list	48 hours

Setup Sprint $99 Or start free

Hooks and MCP servers are in Sprint, not Lite — which one you actually need. Clocks run from a complete intake, not from the Stripe receipt.