What hooks enable
Hooks add an automation layer to Claude Code without modifying its code. Common uses:
- Auto-format files after writing
- Block dangerous commands (
rm -rf,git push --force) - Show a reminder each time Claude finishes responding
- Preserve key info before compaction
- Ask an LLM “is this change safe?” and block on the answer
Configuration locations
| File | Scope |
|---|---|
~/.claude/settings.json | User-global |
.claude/settings.json | Project (committed) |
.claude/settings.local.json | Personal local (gitignored) |
Basic structure
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
}
]
}
]
}
}
Common events
| Event | When it fires | Use case |
|---|---|---|
| PreToolUse | Before a tool call executes | Block dangerous commands, permission checks |
| PostToolUse | After a tool call succeeds | Auto-format, run tests |
| PostToolUseFailure | After a tool call fails | Error logging, notifications |
| PermissionRequest | When a tool call needs a permission decision | Automate approval decisions |
| UserPromptSubmit | When a prompt is submitted | Prompt analysis, context injection |
| Stop | When Claude finishes responding (every turn) | Check whether work is done, reminders |
| PreCompact | Before context compaction | Preserve key info separately |
| SessionStart | When a session begins or resumes | Environment check, intro message |
| SessionEnd | When a session terminates | Cleanup (JSON output such as systemMessage is discarded) |
Other events include SubagentStart, SubagentStop, StopFailure, FileChanged, and PreModelSwitch. See the Hooks reference for the full list.
Five hook types
1. command — run a shell command
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
}
Receives the event JSON on stdin. Use jq to extract fields.
2. http — POST to a URL
{
"type": "http",
"url": "http://localhost:8080/hooks/pre-tool-use",
"headers": { "Authorization": "Bearer $MY_TOKEN" },
"allowedEnvVars": ["MY_TOKEN"]
}
Sends the event’s JSON input as the POST request body. The response body uses the same JSON output format as command hooks. Header values only resolve environment variables listed in allowedEnvVars.
3. mcp_tool — call an MCP tool
{
"type": "mcp_tool",
"server": "my_server",
"tool": "security_scan",
"input": { "file_path": "${tool_input.file_path}" }
}
Calls a tool on a configured MCP server. The tool’s text output is treated like command-hook stdout.
4. prompt — ask an LLM
{
"type": "prompt",
"prompt": "Decide if this command makes a destructive system change: $ARGUMENTS. Respond with JSON: {\"ok\": true} if it is safe, or {\"ok\": false, \"reason\": \"your explanation\"} if it is not."
}
$ARGUMENTS is a placeholder for the hook input JSON. The model responds with JSON containing ok and reason, and what happens on ok: false depends on the event. By default the hook uses the model Claude Code uses for background functionality; set model to change it.
5. agent — run an agent
{
"type": "agent",
"prompt": "Verify that unit tests were added alongside the file changes"
}
Spawns a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. Higher token cost. Agent hooks are experimental and may change.
Example: block dangerous commands
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Decide if this shell command permanently deletes data or makes hard-to-reverse changes: $ARGUMENTS. Respond with {\"ok\": true} if not, or {\"ok\": false, \"reason\": \"your explanation\"} if it does.",
"continueOnBlock": true
}
]
}
]
}
}
On PreToolUse, ok: false denies the tool call. By default the turn ends; with continueOnBlock: true the reason goes back to Claude as the tool error so it can adjust and continue.
For command and HTTP hooks that act as a gate, add "onFailure": "block" (Claude Code v2.1.295 or later). A hook that can’t start, times out, or exits with an unexpected code then blocks the action instead of letting it through.
Example: auto-format after write
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; case \"$f\" in *.ts|*.tsx|*.js|*.jsx|*.json|*.md) prettier --write \"$f\";; esac; } 2>/dev/null || true"
}
]
}
]
}
}
Per-extension formatter selection.
Example: message when a response ends
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "echo '{\"systemMessage\": \"Response finished — review changed files.\"}'"
}
]
}
]
}
}
Stop runs when Claude finishes responding, on every turn, not when the session ends. JSON output with systemMessage is shown to the user. SessionEnd fires when the session terminates, but Claude Code discards its JSON output fields such as systemMessage, so use it for cleanup only.
Debugging checklist
- JSON syntax —
jq . settings.jsonto validate - Matcher pattern — exact tool name (e.g.
Write|Edit) - Test the command directly —
echo '{"tool_input":{"file_path":"test.ts"}}' | <hook command> - Check registration —
/hooksopens a read-only browser that labels each hook with where it comes from (user, project, or local settings, a plugin, and so on). Direct edits to settings files are normally picked up automatically by the file watcher. - Debug mode —
claude --debugshows hook execution logs - Disable temporarily — set
"disableAllHooks": truein your settings to rule hooks out. There is no way to disable an individual hook while keeping it in the configuration.
Use hookify
hookify generates hooks from natural language. If hand-writing JSON feels heavy, draft with hookify first and apply the result to settings.json.
Next steps
- hookify — define hooks in plain language
- Claude Code Setup — project-aware hook recommendations
- Writing a Great CLAUDE.md — separate hook automation from CLAUDE.md rules
- Hooks reference — every event, input field, and decision control option