Claude Code Hooks Cheat Sheet
Hooks run your code at fixed points in Claude Code's loop, so a rule is enforced every time instead of hoping the model remembers it. This page has the events, exit codes and JSON fields you need.
Where hooks live and what they look like
| File | Applies to | Commit it? |
|---|---|---|
~/.claude/settings.json | All your projects | No |
.claude/settings.json | This project | Yes |
.claude/settings.local.json | This project, just you | No (gitignored) |
Hooks also come from plugins (hooks/hooks.json), skill and subagent frontmatter, and managed policy settings. Three levels of nesting: event, then a matcher group, then one or more handlers.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-bash.sh" }
]
}
]
}
}Handler type | Runs |
|---|---|
command | A shell command; gets the event JSON on stdin (default timeout 600 s) |
http | POSTs the event JSON to a url |
mcp_tool | Calls a tool on a configured MCP server |
prompt | Asks a model to decide, with $ARGUMENTS as the event JSON (30 s) |
agent | Runs an agent to decide (experimental, 60 s) |
Matchers: "*", "" or no matcher match everything. Edit|Write matches either tool exactly. Anything with other characters is a regex, such as mcp__github__.* for every tool from the github MCP server. The if field narrows tool events further with permission rule syntax, such as "if": "Bash(rm *)".
The events you'll use most
| Event | Fires | Matcher | Exit 2 |
|---|---|---|---|
PreToolUse | Before a tool call | Tool name | Blocks the call |
PostToolUse | After a tool call succeeds | Tool name | Shows stderr to Claude (tool already ran) |
PostToolUseFailure | After a tool call fails | Tool name | Shows stderr to Claude |
PermissionRequest | When a call needs a permission decision | Tool name | Not honored; decide with JSON |
UserPromptSubmit | When you send a prompt | none | Blocks the prompt |
Stop | When Claude finishes responding | none | Keeps Claude working |
SubagentStop | When a subagent finishes | Agent type | Keeps the subagent working |
SessionStart | Session begins or resumes | startup, resume, clear, compact, fork | Stderr shown to you only |
SessionEnd | Session ends | End reason | Stderr shown to you only |
Notification | Claude Code sends a notification | permission_prompt, idle_prompt, ... | Ignored |
PreCompact / PostCompact | Around context compaction | manual, auto | PreCompact: blocks compaction |
ConfigChange | A settings file changes mid-session | Settings source | Blocks the change |
FileChanged | A watched file changes on disk | File names | Stderr shown to you only |
Elicitation | An MCP server asks you for input | Server name | Declines the request |
There are more (33 in total in November 2026), including SubagentStart, TaskCreated, TaskCompleted, PostToolBatch, CwdChanged, WorktreeCreate and InstructionsLoaded. Run /hooks to see what you have configured.
Exit codes
| Exit code | Meaning |
|---|---|
0 | Success. JSON printed to stdout is applied; Claude never sees stderr |
2 | Blocking error. On events that can block, the action stops and your stderr is the reason Claude sees |
| Anything else | Non-blocking error. The action goes ahead (even exit 1) |
To enforce a policy, use exit 2, not exit 1. Exit 2 blocks even if your JSON says allow.
JSON output
| Field | Where | Effect |
|---|---|---|
continue: false + stopReason | Any event | Stops Claude entirely and shows the reason |
systemMessage | Any event | Warning shown to you |
decision: "block" + reason | UserPromptSubmit, PostToolUse, Stop, SubagentStop, PreCompact, ... | Blocks, with the reason fed back |
hookSpecificOutput.permissionDecision | PreToolUse | allow, deny, ask or defer (deny wins over defer, ask, allow) |
hookSpecificOutput.updatedInput | PreToolUse | Rewrites the tool input before it runs |
hookSpecificOutput.additionalContext | PreToolUse, PostToolUse, SessionStart, ... | Adds text to Claude's context |
hookSpecificOutput.decision.behavior | PermissionRequest | allow or deny |
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database writes are not allowed"
}
}Input on stdin always includes session_id, transcript_path, cwd, permission_mode and hook_event_name; tool events add tool_name and tool_input. Useful variables: $CLAUDE_PROJECT_DIR (project root) and, in plugins, $CLAUDE_PLUGIN_ROOT.
Example: block rm -rf before it runs
Save as .claude/hooks/check-bash.sh, make it executable with chmod +x, and register it with the settings above. It needs jq and bash.
#!/usr/bin/env bash
# PreToolUse hook for Bash: refuse rm with both a recursive and a force flag.
cmd=$(jq -r '.tool_input.command // ""')
while IFS= read -r part; do
set -f; set -- $part; set +f # split this command into words
[ "$1" = sudo ] && shift
[ "$1" = rm ] || continue
r=0; f=0
for w in "$@"; do
case "$w" in
--recursive) r=1 ;;
--force) f=1 ;;
--*) ;;
-*) case "$w" in *[rR]*) r=1 ;; esac
case "$w" in *f*) f=1 ;; esac ;;
esac
done
if [ "$r" = 1 ] && [ "$f" = 1 ]; then
echo "Blocked: rm with recursive and force flags. Delete specific paths instead." >&2
exit 2
fi
done < <(printf '%s
' "$cmd" | tr ';&|' '
')
exit 0It catches rm -rf, rm -Rf, rm -r -f and --recursive --force, including after sudo or &&, and lets rm file.txt and git rm -rf --cached through. It is a guardrail against mistakes, not a security boundary: a determined command can delete files other ways.
For a full walkthrough see the Claude Code hooks tutorial, and the Claude Code cheat sheet for commands and shortcuts.