Hook Event Matcher Handler — Claude Code Guide

Hook: event → matcher → handler

A hook is local automation that reacts to a Claude Code lifecycle event. Unlike MCP, it does not connect an external source; it runs a local command or script in response to an event.

The event identifies when to react, the matcher narrows the condition, and the handler performs one predictable action.

Part	Question
Event	When should it react?
Matcher	For which tool, path, or pattern?
Handler	Which one action should it perform?

Event groups

Before tool use — check or block a risky action.
After tool use or file change — format, check, or report.
Session lifecycle — show rules, reminders, or session state.

Keep matchers narrow

A matcher may filter path, tool type, command pattern, or other supported context. Format only the needed src/**/*.ts and src/**/*.tsx rather than every repository file.

A broad matcher creates noise, delay, and loss of trust in automation.

Schematic after-edit hook

{"event":"afterFileEdit","matcher":{"paths":["src/**/*.ts","src/**/*.tsx"]},"handler":{"command":"prettier --write {{file}}"}}

One handler, one understandable action

Format the changed file.
Guard a protected path.
Run a small local check.
Show a session reminder.
Move complex multi-step logic into a script, tool, or skill.

What a hook does not replace

A hook should not plan complex work, analyze the whole codebase, make business decisions, replace a task spec or tests, or act as a hidden orchestrator. Keep project hooks in the repository beside CLAUDE.md, skills, and agents so changes are reviewable.