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.

FileApplies to
~/.claude/settings.jsonAll your projects, on this computer
.claude/settings.jsonOne project, and can be committed for the team
.claude/settings.local.jsonOne project, for you only
Managed settingsA whole organization, set by an administrator
A plugin’s hooks/hooks.jsonWherever the plugin is enabled
Skill or subagent frontmatterWhile 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.

EventWhen it firesCan it decide?
StopClaude finished responding, at the end of each turnCan send Claude back to work
StopFailureThe turn ended on an API error, such as a rate limitNo
NotificationClaude Code sends a notification: a prompt waiting, idle, a sign-inNo
PermissionRequestJust before a permission prompt appearsAllow or deny
PreToolUseBefore every tool call, including AskUserQuestionAllow, deny, ask, or answer a question
ElicitationAn MCP server asks you for inputAccept, 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 codeMeaning
0Success. Claude Code reads your JSON, if you printed some
2Blocking error. On events that can block, the action stops and your standard error becomes the reason. PermissionRequest ignores it
Anything elseNon-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

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.

Download on the App Store