Skip to content
BENIBIX Learn

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.

AI⌨️ Claude Code

Hook Matcher

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

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.
Why it matters
It is the main way to keep a hook from running on everything.
Full entry
AI⌨️ Claude Code

Hook if Condition

A field that runs a hook only when the call matches one rule.

The if field on a hook holds one permission rule, such as Bash(git *), and the hook runs only when the tool call matches it. It narrows a hook further than the matcher, which only sees the tool name. For Bash it checks each part of a command, so Bash(git *) matches npm test && git push. It holds exactly one rule, with no and or or.

Example
Lucy's hook only cares about git push. She adds an if rule for it, and the hook stops running on every other command.
Why it matters
It saves a script start on every call the hook would just ignore.
Full entry

In one line

Hook Matcher
The field that picks which tools or events a hook runs on.
Hook if Condition
A field that runs a hook only when the call matches one rule.