Getting started
Introduction
Claude Code hooks run shell commands, HTTP endpoints, MCP tools, prompts, or agents at lifecycle events. This sheet covers matchers, output, and decisions.
- Hooks reference (code.claude.com)
- Hooks guide (code.claude.com)
Anatomy
flowchart LR
accTitle: Hook anatomy
accDescr: PreToolUse uses Edit|Write; Notification an empty matcher.
subgraph event ["`**Event**`"]
direction TB
PreToolUse["`**PreToolUse**<br>before a tool call`"]
Notification["`**Notification**<br>Claude needs input`"]
end
subgraph matcher ["`**Matcher group**`"]
direction TB
EditWrite["`**Edit|Write**<br>either tool`"]
Empty["`**#quot;#quot;**<br>every event`"]
end
subgraph handler ["`**Handler**`"]
direction TB
Command["`**command**<br>runs a shell command`"]
end
PreToolUse --> EditWrite --> Command
Notification --> Empty --> Command
A hook event fires at a lifecycle point. Its matcher group filters the event, then matching handlers run in parallel.
See: Hooks reference
First hook
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt",
"hooks": [
{ "type": "command",
"command": "notify-send 'Claude Code' 'Needs input'" }
]
}
]
}
}
Run /hooks to confirm the hook loaded. On macOS, use osascript instead of notify-send.
Everyday hooks
Format after edits
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command",
"command": ".claude/hooks/format.sh" }
]
}
]
}
}
The script reads .tool_input.file_path with jq, then formats that file. Make it executable with chmod +x.
Block protected files
settings.json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command",
"command": ".claude/hooks/protect-files.sh" }
]
}
]
}
}
protect-files.sh
#!/bin/bash
f=$(jq -r '.tool_input.file_path // empty')
case "$f" in
*.env|*/package-lock.json|*/.git/*)
echo "Protected file: $f" >&2; exit 2 ;;
esac
exit 0
Exit 2 blocks the edit and shows stderr to Claude. Use the permission system for hard allow and deny rules.
Notify when needed
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [
{ "type": "command",
"command": "notify-send 'Claude Code' 'Needs input'" }
]
}
]
}
}
permission_prompt waits about six seconds; idle_prompt about 60 seconds.
Add context
settings.json
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{ "type": "command",
"command": ".claude/hooks/context.sh" }
]
}
]
}
}
context.sh
#!/bin/bash
echo '{"hookSpecificOutput":{
"hookEventName":"SessionStart",
"additionalContext":"Run pnpm test before committing"
}}'
Injected context stays under 10,000 characters per field.
Run in background
{
"type": "command",
"command": ".claude/hooks/run-tests.sh",
"async": true,
"asyncRewake": true
}
Async hooks don't block the turn; asyncRewake wakes Claude on exit 2 and shows stderr as a system reminder.
Events
Session
| Event | Fires when |
|---|---|
SessionStart | Session begins or resumes |
Setup | Init-only or maintenance run |
PreCompact | Before context compaction |
PostCompact | After compaction |
ConfigChange | A settings file changes |
SessionEnd | Session terminates |
See: Hook lifecycle
Prompts
| Event | Fires when |
|---|---|
UserPromptSubmit | Prompt submitted, before processing |
UserPromptExpansion | A command expands into a prompt |
Stop | Claude finishes responding |
StopFailure | Turn ends on an API error |
Notification | A notification is sent |
See: Hook events
Tools
| Event | Fires when |
|---|---|
PreToolUse | Before a tool call; can block |
PermissionRequest | A tool needs a decision |
PermissionDenied | Auto mode denies a call |
PostToolUse | Tool call succeeds |
PostToolUseFailure | Tool call fails |
PostToolBatch | A parallel batch resolves |
See: Hook events
Files and agents
| Event | Fires when |
|---|---|
FileChanged | A watched file changes |
CwdChanged | The working directory changes |
DirectoryAdded | /add-dir adds a directory |
InstructionsLoaded | CLAUDE.md is loaded |
SubagentStart | A subagent is spawned |
SubagentStop | A subagent finishes |
See: Hook events
Configuration
Locations
| File | Scope |
|---|---|
~/.claude/settings.json | All your projects |
.claude/settings.json | One project, shareable |
.claude/settings.local.json | One project, personal |
| Managed settings | Organization-wide |
Plugin hooks/hooks.json | While plugin is enabled |
| Skill frontmatter | After invocation, until /clear |
| Subagent frontmatter | While that subagent runs |
Hook entries merge across scopes instead of replacing each other.
See: Hook locations
Matchers
| Value | Meaning |
|---|---|
*, "", or omitted | Every occurrence |
Bash | Exact tool name |
Edit\|Write | Either tool |
^Notebook | Regex: name starts with |
mcp__memory__.* | Regex: server tools |
Regex applies when the value contains characters outside letters, digits, _, -, spaces, ,, and |.
See: Matcher patterns
Handler types
| Type | Runs |
|---|---|
command | Shell command; JSON on stdin |
http | POST event JSON to a URL |
mcp_tool | Call a configured MCP tool |
prompt | Single-turn model decision |
agent | Subagent with Read, Grep, Glob |
Prompt and agent hooks are capped at 12 concurrent runs.
See: Hook handler fields
Fields
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(git *)",
"command": ".claude/hooks/git-check.sh",
"timeout": 30,
"statusMessage": "Checking git command"
}
]
}
if filters five tool events; on other events the hook never runs. Commands default to 600s, prompts to 30s, and agents to 60s.
See: Common fields
Disable
| Command | Effect |
|---|---|
/hooks | Browse loaded hooks |
claude --settings '{"disableAllHooks": true}' | Disable for one run |
claude -p --bare "review this" | Skip hooks and plugins |
disableAllHooks temporarily disables unmanaged hooks; managed hooks need managed settings. --settings overrides project settings for one run. Delete a hook's entry to remove it.
Decisions
Exit codes
| Code | Result |
|---|---|
0 | Success; apply JSON on stdout |
2 | Block when supported; stderr explains |
| other | Non-blocking error |
onFailure: "block" also blocks on hook failure. On events that cannot block, exit 2 is ignored or only surfaces stderr; see exit code behavior per event.
See: Exit code output
JSON output
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destructive command"
}
}
Exit 0 and print only JSON for finer control than exit codes.
See: JSON output
Output fields
| Field | Effect |
|---|---|
decision: "block" | Reject a prompt or add feedback |
continue: false | Stop Claude entirely |
systemMessage | Warn the user |
terminalSequence | Emit an allowed OSC sequence |
permissionDecision and additionalContext are per-event; put them in hookSpecificOutput with hookEventName.
See: Decision control
Also see
- Claude Code cheatsheet (devhints.io)
- Claude Code commands (devhints.io)
- Agent skills (devhints.io)
- Hooks reference (code.claude.com)
- Hooks guide (code.claude.com)
0 Comments for this cheatsheet. Write yours!