Hooks — Make Claude Code Run Your Rules Every Time
In the last post we looked at subagents — separate helpers that run a task in their own context and report back. Today we cover the other Core Building Block: hooks. A subagent is extra hands. A hook is a rule that fires on its own — the difference between hoping Claude does something and making sure it always happens.
What a hook actually is
Straight from the official docs: hooks are user-defined shell commands that run at specific points in the Claude Code lifecycle. They give deterministic control — meaning they run every time, instead of relying on the model to choose to run them. CLAUDE.md is guidance the model usually follows but can skip. A hook is not guidance: when the event fires, the command runs.
The lifecycle events you will use
- SessionStart — when a session begins or resumes
- UserPromptSubmit — when you submit a prompt, before Claude reads it
- PreToolUse — before a tool call runs; it can block the call
- PostToolUse — after a tool call succeeds (great for auto-format)
- Stop — when Claude finishes responding
- SessionEnd — when the session ends
Auto-format after every edit
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r \".tool_input.file_path\" | xargs npx prettier --write" }
]
}
]
}
}Block a tool before it runs
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r ".tool_input.command")
if echo "$COMMAND" | grep -q "drop table"; then
echo "Blocked: dropping tables is not allowed" >&2
exit 2
fi
exit 0You put hooks in a settings file. Project hooks live in .claude/settings.json and can be committed so your whole team gets them. Personal hooks live in ~/.claude/settings.json for every project on your machine. Run /hooks inside Claude Code to see everything configured — or just describe the hook you want and let Claude write it.
Try it: add an auto-format hook
Enough theory — let us build a real one in a minute. This hook runs Prettier on every file Claude edits, so your formatting stays clean without you ever asking. It is a PostToolUse hook, matched to the Edit and Write tools. Follow these steps in your own project.
- Open .claude/settings.json in your project root. If the file is not there, create it.
- Add the hooks block below — a PostToolUse handler with the matcher Edit|Write. If a hooks key already exists, add PostToolUse inside it — do not replace the whole object.
- Save the file. Claude Code picks up the change on its own within a few seconds.
- Type /hooks to confirm it registered — you will see PostToolUse in the list with your command under it. Then ask Claude to edit any file.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r \".tool_input.file_path\" | xargs npx prettier --write" }
]
}
]
}
}Here is what you will see: every time Claude finishes an Edit or a Write, the file is formatted automatically — no reminders, no manual prettier run. The tool call succeeds first, then the hook fires on that file path and Prettier rewrites it in place. Deterministic, every single time.
One more thing worth knowing: swap PostToolUse for PreToolUse and an exit code 2 from your script blocks the tool before it runs — that is how you stop an edit instead of just cleaning up after it.
Next post: managing context and cost — /clear, /compact, and prompt caching.