Claude Code hooks explained
Hooks are shell commands or prompts that Claude Code runs automatically at specific points in a session, like before a tool call or when Claude tries to stop. They can block an action, inject context, or ask a question, and Anthropic documents more than 25 distinct hook events.
Last verified 29 September 2026. Every priced or limited claim below links to its source.
Which hook events do people use?
PreToolUse fires before a tool call executes and can block it outright, the hook most people reach for first to stop a dangerous shell command before it runs. PostToolUse fires after a tool succeeds and can react to the result or log it, but cannot undo the action since the tool already ran. source, checked 29 September 2026.
Stop fires when Claude finishes responding and can block the stop, forcing Claude to keep working, the mechanism behind completion checks that refuse to let a session end until a stated condition is met. SessionStart fires when a session begins or resumes and is the usual place to load project context automatically. source, checked 29 September 2026.
What can a hook block?
Only some events support blocking. PreToolUse, UserPromptSubmit, Stop, SubagentStop and a handful of others can stop the action outright with exit code 2 or a decision field. PostToolUse and PostToolUseFailure cannot block anything, since the tool call already happened by the time they fire, they can only show Claude a message about what happened. source, checked 29 September 2026.
Command hooks or prompt hooks?
A command hook runs a shell command and reads its exit code and output. A prompt hook instead asks Claude a question in natural language and reads back a structured yes or no style answer, useful for judgment calls a fixed script cannot make, like whether a task is genuinely complete. source, checked 29 September 2026.
How do hooks fit with CLAUDE.md?
CLAUDE.md is read once and treated as a suggestion the model tries to follow. A hook is enforced code that runs whether or not the model feels like it: Anthropic's own docs are explicit that a PreToolUse hook, not a CLAUDE.md instruction, is the way to actually block an action regardless of what Claude decides. Mover OS installs several of these hooks by default so its own rules cannot simply be argued around mid session. Mover OS is not for anyone who does not use Claude Code, since those hooks run only there.
Common questions
Do hooks slow Claude Code down?
Each hook runs with a timeout, 600 seconds by default for most events, 30 seconds for UserPromptSubmit, so a hanging hook script can delay a turn until it times out rather than blocking forever.
Can a hook see what a subagent is doing?
Yes. Hooks from settings files, managed policy and plugins also run inside subagents, and the input carries an agent_id and agent_type identifying which subagent triggered the event.
Is there a simpler way to add hooks without writing JSON by hand?
Claude Code ships a plugin system and a hook development skill that scaffolds common patterns; most people start by copying a working example rather than writing the schema from scratch.
Hooks and the instructions file work together, and the file comes first. Or Mover OS, $49 once. It is the wrong choice if you want something that keeps running while your computer is off.