Claude Code plugin hooks not firing: what to check
A plugin hook that never runs is usually not loaded, mismatched on event or matcher, or blocked by a setting. The documented checks, in order.
Run /hooks in your Claude Code session first. If the plugin's hook is not listed, Claude Code did not load it, and the cause is the plugin or a setting. If it is listed but never runs, the cause is usually the event name or the matcher. This guide follows Anthropic's documentation as read in November 2026.
For what hooks are and which plugins ship them, see our Claude Code hooks page.
Where a plugin declares its hooks
The docs give two places, and both load:
hooks/hooks.jsonat the plugin root. The event map must sit under a top-level"hooks"key. The plugins reference says a file with only the event map, without that wrapper, fails to load.- The
hookskey in.claude-plugin/plugin.json, as a file path, an inline object, or an array of both. Claude Code merges it withhooks/hooks.jsonwhen that file exists.
The hooks/ folder belongs at the plugin root, not inside .claude-plugin/.
How events and matchers decide whether a hook runs
Each hook sits under an event such as PreToolUse, PostToolUse, SessionStart or Stop. The plugin troubleshooting page says event names are case-sensitive. The matcher field then filters within that event. The hooks reference describes three cases:
"*", an empty string, or no matcher: the hook fires on every occurrence of the event.- Only letters, digits,
_,-, spaces,,and|: an exact string, or a list of exact strings.Edit|Writematches either tool. - Any other character: an unanchored JavaScript regular expression.
Edit.*also matchesNotebookEdit.
For tool events the matcher is tested against the tool name. Some events, including UserPromptSubmit and Stop, have no matcher support and always fire.
Why a plugin hook does not run
The plugin is disabled or not loaded
The hooks reference lists plugin hooks as active "when plugin is enabled". Claude Code registers them when a session loads the plugin. If you installed the plugin during the current session, the troubleshooting page says to run /reload-plugins. Turning plugins on and off is covered in turn off or remove a plugin.
The hooks file failed to load
The /plugin Errors tab shows these documented messages:
Failed to load hooks from <path>: <reason>:hooks/hooks.jsonis not valid JSON or fails the hooks schema.hooks path not found: <path>: the manifest'shooksfield names a file that does not exist.hooks path escapes plugin directory: <path>: the path resolves outside the plugin root.
The docs add that until hooks/hooks.json is fixed, a session loads the plugin without the hooks in that file.
Wrong event name or matcher
The debug guide calls the matcher "the usual cause" when a hook is listed but does not fire. The documented mistakes:
- A lowercase tool name such as
bash. Matching is case-sensitive and tool names are capitalized:Bash,Edit,Write,Read. - A misspelled tool name, which matches nothing and fails silently.
- A
matcherwritten as a JSON array instead of a single string. - A comma separator on a version before v2.1.191. Use
|there. - For the plugin's own MCP tools, a matcher on the server name alone. The full name is
mcp__plugin_<plugin>_<server>__<tool>.
The script path or permissions are wrong
Reference bundled scripts with ${CLAUDE_PLUGIN_ROOT}, the plugin's installation directory. In a shell-form command, wrap it in double quotes. The docs say an unquoted variable breaks when the install path contains a space, and the error shows the path cut off at that space. The hooks guide also states that hook scripts must be executable, with the fix chmod +x on the script.
A hook can also fail with Failed to run: Plugin directory does not exist: <path>. The docs say to run /reload-plugins first, even though the message says to reinstall.
Another plugin has the same name
When two enabled plugins share a name, only one registers its hooks/hooks.json hooks. The plugin's details in /plugin then show a note that begins Its hooks.json hooks do not run.
A setting or managed policy turns hooks off
"disableAllHooks": truein a settings file disables all hooks. Which settings file wins is explained in plugin scope.allowManagedHooksOnlyin managed settings blocks user, project, local and plugin hooks. Hooks from plugins force-enabled in managed settingsenabledPluginsare exempt. The/hooksmenu showsOnly hooks from managed settings run here.
You are in chat, not Cowork or Claude Code
Anthropic's component support table marks hooks as "Ignored" in chat and "Loads" in Cowork and Claude Code. In a chat conversation, a plugin's hooks never run by design.
How to check, in order
- Run
/plugin, open Installed and confirm the plugin is enabled. Then read the Errors tab. - Run
/reload-plugins. It printsReloaded:with counts of plugins, skills, agents, hooks and servers. - Run
/hooks. It is a read-only list that labels each hook with its source, including the plugin's name. - Compare the event name and matcher against the hooks reference, character by character.
- Start a session with
claude --debug, trigger the event, and read the log at~/.claude/debug/<session-id>.txt. A hook that ran appears with its exit code. The flag does not print to the terminal. - If it is your own plugin, run
claude plugin validate <plugin-directory>in your shell. It catches JSON syntax problems inhooks/hooks.jsonand warns about unquoted path variables. See also plugin validation failed.
A hook can run and leave no trace. The docs say a PostToolUse hook that exits 0 shows nothing in the transcript, so check the debug log or the script's own effect first.
What the documentation does not say
The pages read do not say whether the /hooks menu or debug logging are available in Cowork. They also describe no way to turn off one plugin hook while keeping the rest of the plugin.
Sources
Read more
Claude Code plugin scope: user, project or local?
The -s flag decides who gets a plugin and whether it travels in git. What each scope writes, which one wins, and which to pick. Tested on v2.1.325.
Claude plugin validation failed? Check the package first
Most plugin validation errors are package problems, not Claude problems. The real error messages and the fixes, tested on v2.1.296.
Plugin installed but skills are missing: what to check
The plugin shows as installed but Claude never uses its skills. The documented causes, in check order.
Claude Code marketplace not found: how to fix it
A typo'd marketplace name surfaces as a plugin-not-found error. The real error messages and the checks that fix them.