Claude Code hooks explained, with examples
Updated
Quick answer
A Claude Code hook is a command that Claude Code runs at a fixed point in a session: before a tool call, when it needs a permission, when a turn ends. Hooks live in settings.json, receive JSON on standard input and can answer with JSON or an exit code. Use them for what must happen every time, such as a notification or a check, rather than asking Claude to remember.
What a hook is
An instruction in CLAUDE.md is something Claude tries to follow. A hook is something Claude Code does, every time, whatever the model decides. That makes hooks the right tool for anything that must not depend on memory: format a file after each edit, block a command, show a notification, log a decision.
Most hooks are shell commands ("type": "command"). Claude Code also accepts http hooks, which POST the same JSON to a URL, mcp_tool hooks, which call a tool on an MCP server, and prompt and agent hooks, which ask a model to decide. A command hook runs with your full user permissions, so read any hook before you add it.
Where hooks live
A hook is three levels of JSON: an event, a matcher group that filters when it fires, and one or more handlers. This one runs a script after every file edit or write:
~/.claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/format.sh" }]
}
]
}
}
Swipe the table sideways to see both columns.
| File | Applies to |
|---|---|
~/.claude/settings.json | All your projects, on this computer |
.claude/settings.json | One project, and can be committed for the team |
.claude/settings.local.json | One project, for you only |
| Managed settings | A whole organization, set by an administrator |
A plugin’s hooks/hooks.json | Wherever the plugin is enabled |
| Skill or subagent frontmatter | While that skill or subagent is active |
Hooks from different files add up rather than replace each other. The same handler defined in two settings files runs once; a plugin’s copy runs separately. In an interactive session, Claude Code holds back hooks, even your own, until you accept the trust dialog for the folder. Cloud sessions don’t read your local ~/.claude/settings.json.
The events that matter for notifications
Claude Code has more than thirty events. Six of them cover everything a notification needs:
Swipe the table sideways to see all columns.
| Event | When it fires | Can it decide? |
|---|---|---|
Stop | Claude finished responding, at the end of each turn | Can send Claude back to work |
StopFailure | The turn ended on an API error, such as a rate limit | No |
Notification | Claude Code sends a notification: a prompt waiting, idle, a sign-in | No |
PermissionRequest | Just before a permission prompt appears | Allow or deny |
PreToolUse | Before every tool call, including AskUserQuestion | Allow, deny, ask, or answer a question |
Elicitation | An MCP server asks you for input | Accept, decline or cancel |
SessionStart and SessionEnd mark the edges of a session, and SubagentStop the end of a subagent’s work.
Matchers, input and output
A matcher filters by the event’s main field: the tool name for tool events, the notification type for Notification, the server name for Elicitation. Letters, digits, _, - and | are matched exactly, so Edit|Write means either tool; anything else is a regular expression, such as mcp__github__.*. An empty matcher, or none, matches everything. Some events, Stop among them, take no matcher at all. For tool events, an if field narrows further with permission rule syntax: "if": "Bash(git *)".
Every hook receives JSON on standard input: session_id, cwd, transcript_path, hook_event_name, often permission_mode, plus the event’s own fields. To answer, print one JSON object on standard output and exit 0. Decisions go in hookSpecificOutput or, for Stop, in top-level decision and reason. systemMessage shows a warning to you, additionalContext gives Claude a note, and terminalSequence asks Claude Code to emit a notification or bell for you, since hooks have no terminal of their own. Print nothing else: a line your shell profile echoes at startup is enough to make Claude Code read your JSON as plain text.
Exit codes and timeouts
| Exit code | Meaning |
|---|---|
| 0 | Success. Claude Code reads your JSON, if you printed some |
| 2 | Blocking error. On events that can block, the action stops and your standard error becomes the reason. PermissionRequest ignores it |
| Anything else | Non-blocking error. The action goes ahead and you see a hook error notice |
A command hook gets 600 seconds by default, 30 on UserPromptSubmit; set timeout, in seconds, to change it. A hook that times out is cancelled and its output ignored. To make a failing or timed-out hook block the action instead of letting it through, set "onFailure": "block" (version 2.1.295 or later). "async": true runs a hook in the background without holding Claude up; "asyncRewake": true does the same and wakes Claude when the hook exits with code 2.
Check your hooks with /hooks
Type /hooks in Claude Code for a read-only list of every hook, with the file or plugin it comes from; select one to see its full command. To see what a hook did, start Claude Code with claude --debug and read the log in ~/.claude/debug/: each run leaves a line with its exit status and duration. To switch all hooks off for a while, set "disableAllHooks": true. Edits to hooks in settings files are normally picked up without a restart.
Hooks are also how notifier apps plug in. Monish’s install command adds six of them to ~/.claude/settings.json. PermissionRequest, Stop and Elicitation send permission prompts, questions, forms and finished turns to your iPhone with buttons to answer. StopFailure sends an alert when a turn ends on an API error. PostToolUse and UserPromptSubmit keep the session card on your lock screen up to date with the step Claude is on, and close on your iPhone a request you answered at the keyboard.
Questions
- Do hooks run in the VS Code extension and the desktop app?
- Yes. Claude Code runs hooks, not the terminal, so they fire there too. The Notification hook’s permission_prompt timing differs in those hosts.
- Can a hook read my whole conversation?
- It receives transcript_path, the path to the session file, which can lag behind the conversation. Stop hooks get Claude’s last reply directly in last_assistant_message.
- Can Claude write a hook for me?
- Yes. Describe what you want and Claude can add it to your settings. Check it with /hooks before you rely on it.
- Why does my hook not run in a new folder?
- In an interactive session, Claude Code holds back hooks until you accept the folder’s trust dialog.
More guides
- The Claude Code Notification hookWhen it fires, what notification_type means, and why it waits six seconds.
- The Claude Code Stop hookRun a command when Claude finishes, or send it back to work without a loop.
- The Claude Code PermissionRequest hookAnswer a permission prompt from a script: input, output, limits.
- Claude Code notifications not working: five causesIs the hook loaded, does it run, is it the right event.
New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.
Get Monish on your iPhone
Free, no account. Your 6-digit code is waiting in the app.