Claude Code hooks: 6 examples and a quick reference
Copy-paste Claude Code hooks: notifications, auto-format, blocking protected files, context after compaction, a Bash log, and a Stop check. Plus a reference.
You tell Claude Code in CLAUDE.md to run Prettier after every edit. Most of the time it does. Sometimes it doesn't, and the pull request fails lint.
That is the gap hooks close. A hook is a shell command Claude Code runs at a fixed point in its lifecycle. Anthropic's hooks guide describes this as deterministic control: certain actions always happen rather than relying on the model to choose them. This post gives six working examples and a quick reference, checked against Anthropic's documentation on 16 November 2026.
How hooks work, in 30 seconds
A hook has three parts: an event (when it runs), an optional matcher (which tool or source it applies to), and a command. Claude Code passes the event's details to the command as JSON on stdin. The command answers with its exit code:
- Exit 0: no objection. For
SessionStartandUserPromptSubmit, whatever the command prints is added to Claude's context. - Exit 2: block, where the event allows it. What the command writes to stderr is shown to Claude as the reason.
Hooks live in a settings file. After adding one, type /hooks in Claude Code to confirm it appears. Several examples below use jq to read the JSON input.
Example 1: get notified when Claude needs you
Runs when Claude Code sends a notification, such as when it is waiting for input or permission. Add to ~/.claude/settings.json (macOS shown):
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
If no notification appears on macOS, the documentation notes that Script Editor may lack notification permission; run osascript -e 'display notification "test"' once in Terminal so it shows up in your notification settings.
Example 2: format every file Claude edits
Runs after any successful Edit or Write, and passes the edited file to Prettier. Add to .claude/settings.json in the project:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
A successful hook shows nothing in the conversation. Check that the file was reformatted.
Example 3: block edits to protected files
Runs before any Edit or Write, and blocks changes to applied migrations. Save as .claude/hooks/protect-migrations.sh and make it executable with chmod +x:
#!/bin/bash
FILE_PATH=$(jq -r '.tool_input.file_path // empty')
if [[ "$FILE_PATH" == *"db/migrations/"* ]]; then
echo "Blocked: applied migrations are read-only. Create a new migration." >&2
exit 2
fi
exit 0
Register it:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-migrations.sh"
}
]
}
]
}
}
Claude sees the blocked reason and can plan around it, for example by writing a new migration instead. For simple path or command blocks, a deny rule may be enough; see Claude Code permissions.
Example 4: bring context back after compaction
When a long session is compacted, the conversation is replaced by a summary. A SessionStart hook with the compact matcher runs after each compaction, and whatever it prints is added back into Claude's context:
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{ "type": "command", "command": "cat .claude/after-compact.md" }
]
}
]
}
}
Keep .claude/after-compact.md to a few lines: the current task, and the rules that must not be lost. The documentation also suggests dynamic output, such as git log --oneline -5. For what compaction keeps and drops, see compaction.
Example 5: keep a log of every shell command
Runs before every Bash tool call, appends the command to a log, and exits 0 so nothing is blocked:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/bash-commands.log"
}
]
}
]
}
}
Useful for reviewing what an agent ran during a long autonomous session.
Example 6: don't let Claude stop until the work is done
A Stop hook runs when Claude finishes responding. Instead of a shell command, this one uses a prompt-based hook: a model checks whether the requested tasks are complete. If it answers "ok": false, Claude keeps working and uses the reason as its next instruction.
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
}
]
}
]
}
}
Stop hooks have a block cap, so they can't keep Claude running forever. Use them for checks you can state clearly, such as "tests pass" or "every file in the task list was changed".
Quick reference: common events
| Event | When it fires | Can block? |
|---|---|---|
SessionStart | A session begins, resumes, or is compacted | No; stdout is added to context |
UserPromptSubmit | You submit a prompt, before Claude processes it | Yes |
PreToolUse | Before a tool call | Yes, with exit code 2 |
PostToolUse | After a tool call succeeds | No; it already ran |
Notification | Claude Code sends a notification | No |
Stop | Claude finishes responding | Yes, up to a cap |
SubagentStart / SubagentStop | A subagent starts or finishes | Varies |
PreCompact / PostCompact | Around context compaction | Varies |
InstructionsLoaded | A CLAUDE.md or rules file loads | No |
SessionEnd | A session terminates | No |
There are more than thirty events in total, including FileChanged, ConfigChange, and worktree events. Besides command, hooks can be http, mcp_tool, prompt, or agent; agent hooks are marked experimental.
Quick reference: where hooks live
| Location | Applies to | Shared? |
|---|---|---|
~/.claude/settings.json | All your projects | No, your machine only |
.claude/settings.json | One project | Yes, committed to the repo |
.claude/settings.local.json | One project | No, kept out of git |
| Managed policy settings | The whole organization | Yes, admin-controlled |
A plugin's hooks/hooks.json | Wherever the plugin is installed | Yes, through the plugin |
If /hooks says only hooks from managed settings run, your organization has turned on allowManagedHooksOnly, and hooks in your own settings files won't run. For how the settings files themselves work, see Claude Code settings.json.
When a hook isn't running
- Run
/hooksand confirm it is listed under the right event. - Check the file location:
.claude/settings.jsonfor project hooks,~/.claude/settings.jsonfor global ones. - Make sure scripts are executable and
jqis installed. - Keep matchers narrow. An empty matcher on a permission hook can apply to every tool.
Hooks run with your permissions
A hook is a shell command that runs on your machine with your access. Read the hooks in any project's .claude/settings.json before you trust the folder, the same way you would read a script before running it. Organizations that need control can use managed settings and allowManagedHooksOnly.
What hooks can't do
Hooks enforce rules you can check mechanically: this path, this command, this test. They can't know that the team decided last week to stop supporting a payment provider, or that a pricing rule changed in a Slack thread. Rules like that change, have an owner, and come from outside the repo.
Where Lockstep fits
Lockstep handles the decisions hooks can't express. It captures decisions from PRDs, Slack, and pull requests, each binding once its owner approves it, and briefs Claude Code on the ones that apply at the start of each session. It uses Claude Code's own hook mechanism to do that. An opt-in check can flag code changes that may conflict with a decision; it is advisory, not a block.
Keep mechanical rules in hooks. Session briefings work with Claude Code today. See how it works.
Sources checked 16 November 2026
- https://code.claude.com/docs/en/hooks-guide
- https://code.claude.com/docs/en/hooks
- https://code.claude.com/docs/en/context-window
Related reading
For why CLAUDE.md alone isn't enough, see why Claude Code ignores your CLAUDE.md. For what goes in CLAUDE.md, see CLAUDE.md examples. For skills, see Claude Code skills: 6 examples. To choose between hooks, skills, subagents, and MCP, see CLAUDE.md vs skills vs hooks vs subagents. For the definition, see Claude Code hooks.
Frequently asked questions
- What are Claude Code hooks?
- User-defined shell commands that Claude Code runs at specific points in its lifecycle, such as before a tool call, after a file edit, or when a session starts. Anthropic describes them as deterministic control: the action always happens rather than relying on the model to choose it.
- Where do I put Claude Code hooks?
- In a settings file. ~/.claude/settings.json applies to all your projects, .claude/settings.json applies to one project and can be committed, and .claude/settings.local.json applies to one project and stays out of git. Organizations can set hooks in managed policy settings, and plugins can ship hooks too.
- How do I block an action with a hook?
- Use a PreToolUse hook whose command exits with code 2 and writes a reason to stderr. Claude Code blocks the tool call and shows the reason to Claude so it can change its approach. Exit 0 means no objection.
- How do I see which hooks are active?
- Type /hooks at the Claude Code prompt to open the hooks browser. If the menu says only hooks from managed settings run, your organization has set allowManagedHooksOnly and your own hooks won't run.
- What is the difference between hooks and CLAUDE.md?
- CLAUDE.md is context: Claude reads it and tries to follow it, with no guarantee. A hook runs regardless of what Claude decides. Use CLAUDE.md for guidance and hooks for anything that must always or never happen.
Keep reading