skip to content

Why does a Claude Code PreToolUse hook with matcher `mcp__github` never fire, and how do Claude Code matchers choose exact or regex matching?

level: middleimportance: should knowfreq 12%

answer

  1. the characters decide the mode
  2. exact list versus regular expression
  3. server prefix alone names no tool
  4. unanchored, so wrap with ^ and $
  5. case counts

basics

~10 s

A matcher of only letters, digits, underscores, hyphens, spaces, commas and pipes is compared exactly, so mcp__github matches no tool. Any other character makes it an unanchored regex; use mcp__github__.*.

solid answer

~30 s

Claude Code decides how to evaluate a `matcher` from its characters. `*`, an empty string or no matcher matches everything. A value made only of letters, digits, `_`, `-`, spaces, `,` and `|` is an exact name or a list of exact names, so `Edit|Write` and `Edit, Write` both mean those two tools. Anything else is a JavaScript regular expression tested unanchored. MCP tools are named `mcp__<server>__<tool>`, so the exact string `mcp__github` equals no tool name; `mcp__github__.*` matches every tool from that server. Because the regex is unanchored, `Edit.*` also matches `NotebookEdit`; write `^Edit$` for a whole-name match. Matching is case-sensitive.

code

json · 18 lines
json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          { "type": "command", "command": "jq -r .tool_name >> ~/mcp-github.log" }
        ]
      },
      {
        "matcher": "^Edit$",
        "hooks": [
          { "type": "command", "command": "/opt/hooks/check-edit.sh" }
        ]
      }
    ]
  }
}

go deeper

for a junior

Recall that the matcher filters on the tool name for tool events and that Edit|Write means either tool.

for a middle

Explain how the characters choose exact or regex evaluation, why mcp__github matches nothing and why Edit.* also hits NotebookEdit.

for a senior

Spot matcher bugs from the configuration alone: unanchored regexes, plugin-scoped MCP names, matchers on events that ignore them, and case mismatches.

for a principal

Set a team convention for matchers in shared settings, such as anchoring regexes and listing exact tools, so a silent non-match cannot disable a policy hook.

## What a matcher is In a Claude Code hook configuration, each event holds a list of **matcher groups**. A group's `matcher` decides whether its handlers run for a given occurrence of the event. For tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`) it is compared with the **tool name**; other events compare it with their own field, as shown below. ## How the value is evaluated Claude Code does not have a flag for "regex mode". It reads the characters: | Matcher value | Evaluated as | Example | |---|---|---| | `"*"`, `""` or omitted | Match everything | every occurrence of the event | | Only letters, digits, `_`, `-`, spaces, `,`, `\|` | Exact string, or a list split on `\|` or `,` | `Bash`; `Edit\|Write`; `Edit, Write` | | Any other character | JavaScript regex, unanchored | `^Notebook`; `mcp__memory__.*` | Consequences that bite: - **A server prefix alone matches nothing.** `mcp__github` contains only exact-match characters, so it is compared with whole tool names such as `mcp__github__search_repositories` and never equals one. The `.*` is required: `mcp__github__.*`. - **Regexes are unanchored.** The test succeeds on a match anywhere in the name, so `Edit.*` fires for `Edit` and for `NotebookEdit`. Use `^Edit$` when you mean exactly one tool, or simply `Edit`, which is exact already. - **Case matters.** `bash` does not match the `Bash` tool. - **Plugin MCP servers carry a scoped name.** A tool from a server bundled in a plugin appears as `mcp__plugin_<plugin-name>_<server-name>__<tool>`, so a matcher written against the bare server key never fires; match `mcp__plugin_my-plugin_db__.*` instead. - **Two events use a narrower exact set.** For `FileChanged` and `StopFailure`, only letters, digits, `_` and `|` count as exact, so a hyphen, space or comma pushes the value onto the regex path, and only `|` separates alternatives. ## Each event matches a different field | Event | Matcher filters on | Example values | |---|---|---| | Tool events | tool name | `Bash`, `Edit\|Write`, `mcp__.*` | | `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact`, `fork` | | `SessionEnd` | why it ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | | `Notification` | notification type | `permission_prompt`, `idle_prompt` | | `SubagentStart`, `SubagentStop` | agent type | `Explore`, `Plan`, a custom agent's `name` | | `PreCompact`, `PostCompact` | trigger | `manual`, `auto` | | `ConfigChange` | configuration source | `project_settings`, `skills` | `UserPromptSubmit`, `Stop`, `PostToolBatch`, `TaskCreated`, `TaskCompleted`, `TeammateIdle`, `WorktreeCreate`, `WorktreeRemove` and a few others have **no matcher support**. A matcher added to one of them is silently ignored and the hook runs every time. `FileChanged` is special in another way: its matcher also builds the watch list, split on `|` into literal filenames. ## Matchers on non-tool events The same exact-or-regex rules apply to the other fields. A few practical examples: - `SessionStart` with `startup|resume` loads context for new and resumed sessions but not after `/clear` or a compaction. - `Notification` with `permission_prompt` alerts only on waiting permission dialogs, not on idle sessions. - `ConfigChange` with `project_settings|local_settings` audits edits to the project's settings files but not to your user settings. - `PreCompact` with `auto` reacts only to automatic compaction, leaving a manual `/compact` alone. ## Narrowing further The group matcher sees only the tool name. To filter on the arguments too, such as only `git` commands inside `Bash`, put an `if` field on the individual handler; that uses permission-rule syntax rather than matcher syntax. ## Debugging a matcher that never fires 1. Run `/hooks` and confirm the hook is listed under the event you meant. 2. Check the exact tool name, including case and, for MCP tools, the full `mcp__<server>__<tool>` form. 3. Ask whether the value is on the exact or the regex path, and whether an unanchored regex matches more than intended. 4. Check that the event supports matchers at all; on one that does not, the matcher is ignored without any error.

  • How do you match a subagent shipped by a plugin, such as `my-plugin:reviewer`, on SubagentStart?
    The agent type is the plugin-scoped identifier, and the colon puts the value on the regex path, so it would match anywhere in a name. Anchor it: `^my-plugin:reviewer$`. A matcher with only the bare frontmatter name, `reviewer`, is an exact string and does not match the scoped identifier.
  • When would you leave the matcher out entirely on PostToolUse?
    When the tool name is the wrong filter, for example a hook that must notice any change after any successful tool call. Omit the matcher or use `*`, then let the script discover what changed, for instance with `git status --porcelain`, and register the same hook on `PostToolUseFailure` for failed calls.

  • A matcher of mcp__github matches every tool from the github server.
  • Regex matchers are anchored to the whole tool name.
  • Hook matchers are case-insensitive.
  • Edit, Write is a regex because it contains a comma.
  • A matcher on Stop filters which turns fire the hook.