Module 07
Hooks: automatic actions at key moments
Developer Tools How Claude Code Works
Module 7 — Hooks: automatic actions at key moments
← Module 6 | Index | Next: Module 8 →
A hook is a command that runs automatically when a specific event happens — without Claude deciding to. If skills are things Claude chooses to do and commands are things you trigger, hooks are things that happen on their own, by rule.
You define hooks in settings.json. Each hook ties an event to a shell command you want to run.
The main events you can hook into
- PreToolUse — right before Claude uses a tool (for example, before it edits a file or runs a command). You can inspect what it’s about to do and even block it.
- PostToolUse — right after a tool finishes. Great for automatic follow-ups.
- UserPromptSubmit — when you send a message, before Claude processes it.
- SessionStart — when a session begins.
- Stop / SubagentStop — when Claude (or a subagent) finishes responding.
- PreCompact — just before the conversation gets compacted (Module 4).
- Notification — when Claude wants your attention.
Why hooks are powerful — concrete examples
- Auto-format code. A PostToolUse hook runs your formatter every time Claude edits a file, so the code is always tidy without you asking.
- Guardrails. A PreToolUse hook blocks edits to protected files (like production config) or refuses dangerous commands. This turns a polite request (“please don’t touch X”) into an enforced rule.
- Run tests automatically after every change, so problems surface immediately.
- Logging and notifications — record what Claude did, or ping you when a long task finishes.
The key difference from CLAUDE.md
A CLAUDE.md request is a suggestion Claude usually follows. A hook is deterministic — it runs every time, guaranteed, because it’s plain code triggered by an event. When you need a rule to be unbreakable, use a hook, not a polite note.
Hooks are an advanced feature and they run real commands on your machine, so build them carefully and only run hooks you trust.