Skip to content
coworkplugins
Guide

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.

By Arun BabuIntermediate

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.json at 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 hooks key in .claude-plugin/plugin.json, as a file path, an inline object, or an array of both. Claude Code merges it with hooks/hooks.json when 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|Write matches either tool.
  • Any other character: an unanchored JavaScript regular expression. Edit.* also matches NotebookEdit.

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.json is not valid JSON or fails the hooks schema.
  • hooks path not found: <path>: the manifest's hooks field 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 matcher written 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": true in a settings file disables all hooks. Which settings file wins is explained in plugin scope.
  • allowManagedHooksOnly in managed settings blocks user, project, local and plugin hooks. Hooks from plugins force-enabled in managed settings enabledPlugins are exempt. The /hooks menu shows Only 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

  1. Run /plugin, open Installed and confirm the plugin is enabled. Then read the Errors tab.
  2. Run /reload-plugins. It prints Reloaded: with counts of plugins, skills, agents, hooks and servers.
  3. Run /hooks. It is a read-only list that labels each hook with its source, including the plugin's name.
  4. Compare the event name and matcher against the hooks reference, character by character.
  5. 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.
  6. If it is your own plugin, run claude plugin validate <plugin-directory> in your shell. It catches JSON syntax problems in hooks/hooks.json and 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