# Hook Matcher

> The field that picks which tools or events a hook runs on.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** matcher

## Think of it like

It is like a sign on a door. It says who may come in.

## Definition

A hook matcher is the matcher field that picks which events a hook group runs on. An empty matcher or * matches all. A value of only letters, digits, _, - and | is an exact name or list, such as Edit|Write. Anything else is a regular expression that can match part of a name, so Edit.* also matches NotebookEdit. Each event matches a different field, such as the tool name.

## Example

Jack wrote Edit.* to match edits. His hook also ran on NotebookEdit. He changes it to ^Edit$ and it stops.

## Example code

```json
{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npm run lint" }] }
    ]
  }
}
```

Run only after Edit or Write.

## Why it matters

It is the main way to keep a hook from running on everything.

## Common mistake

Using a pattern that matches part of a name. Wrap it in ^ and $ for a whole match.

## Three principles

- **Empty matches all.** Or a star.
- **Plain is exact.** Edit|Write.
- **Else a pattern.** Part match.

## Related terms

- [Regular Expression (Regex)](https://learn.benibix.com/term/development/regular-expression)
- [Hook if Condition](https://learn.benibix.com/term/ai/hook-if-condition)
- [Claude Code Hook](https://learn.benibix.com/term/ai/claude-code-hook)

## Told apart from

- [Hook Matcher vs Hook if Condition](https://learn.benibix.com/compare/hook-matcher-vs-hook-if-condition): People think the matcher can pick a command, such as git push. It only sees the tool name, so Bash matches every shell command. The if field reads the call's input, with one permission rule such as Bash(git push *). Use the matcher to pick the tool, and if to pick the calls inside it.

![How a hook matcher is read: empty matches all, plain names match exactly, anything else is a pattern that can match part of a name.](https://learn.benibix.com/diagrams/hook-matcher-rules.svg)

---

Source: https://learn.benibix.com/term/ai/hook-matcher
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
