
Claude Code hooks: shell commands at agent lifecycle points
In short: Claude Code hooks run your shell commands at fixed points in the agent's lifecycle, such as after a file edit, so a rule runs every time without asking.
Claude Code hooks are user-defined commands that Claude Code runs automatically at specific points in its lifecycle, such as before a tool is used, after a file is edited, when you submit a prompt or when a session stops. Anthropic's hooks guide, read in November 2026, says they give deterministic control: the action always happens instead of relying on the model to choose it.
Claude Code hooks in plain words
Instructions are polite requests. Hooks are the door that will not open until the badge is scanned.
How it works
Hooks live in Claude Code's settings files, from your own user settings to project settings and organisation-managed policy settings. Each hook names an event (for example PreToolUse, PostToolUse, UserPromptSubmit, Stop), an optional matcher such as a tool name, and a handler.
Most handlers are shell commands that receive the event details as JSON on standard input. The hooks reference also lists HTTP endpoints, MCP tool calls, LLM prompts and subagents as handler types. A PreToolUse hook can block the tool call by exiting with code 2, and whatever it writes to standard error goes back to Claude as the reason.
Example
Run the formatter after every file edit, as in Anthropic's guide:
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }] }
]
}
}
Where you'll meet it
- Auto-formatting and linting after edits
- Blocking edits to protected paths or secrets files
- Logging every command for audit
- Notifications when a long task finishes
What it changes for you
For developers, hooks turn "please remember to run the linter" into a guarantee. For platform and security teams, hooks are a policy layer, because managed settings apply them across an organisation. Two cautions apply. Hooks run real shell commands on your machine, so review them like scripts. And a hook matched to Edit|Write does not see files changed through shell commands, a gap the guide itself points out.
Claude Code hooks vs CLAUDE.md rules
CLAUDE.md shapes what the model tries to do. Hooks run regardless of what it decides. Use rules for guidance, hooks for guarantees.
Common mistake
My view: writing slow hooks on every tool call. A ten-second check after each edit makes the agent crawl. Keep per-edit hooks fast and move heavy checks to the end of the session or to CI.
Related terms
Claude Code · AGENTS.md and CLAUDE.md · Permission modes · Guardrails · Slash commands
Keep per-edit hooks fast, and move heavy checks to the end of the session or to CI.


