Lifecycle Events
Module: Hooks | Lesson: 2 of 4 | Time: ~10 minutes
What You Will Learn
- What PreToolUse and PostToolUse events are
- How Notification events work
- What SessionStart does and when it fires
Prerequisites
- Completed What Are Hooks?
The Hook Lifecycle
Every Claude Code session follows a lifecycle — a series of events that happen in a predictable order. Hooks let you attach commands to these events. Understanding the lifecycle is key to knowing where to put your hooks.
Here is the full lifecycle with all hookable events:
Session starts
--> SessionStart
--> [Claude thinks and decides to use a tool]
--> PreToolUse
--> [Tool runs]
--> PostToolUse
--> [Claude thinks again, may use more tools...]
--> [Claude wants to send a notification]
--> Notification
--> [Context window is getting full]
--> PreCompact
--> [Compaction happens]
--> PostCompact
--> [Claude finishes or you end the session]
--> Stop
--> SessionEnd
Event Reference
PreToolUse
When it fires: Right before Claude uses any tool (Read, Edit, Bash, etc.)
Why it matters: This is your chance to inspect or block a tool call before it happens. You can prevent Claude from editing certain files, running certain commands, or using certain tools.
Example use cases:
- Block edits to production configuration files
- Require confirmation before running destructive commands
- Log every tool call for audit purposes
If your PreToolUse hook exits with a non-zero code, the tool call is blocked. Claude will see that the tool was prevented and may try a different approach.
PostToolUse
When it fires: Right after a tool finishes running.
Why it matters: This is where you react to what just happened. If Claude edited a file, you can auto-format it. If Claude ran a command, you can check its output.
Example use cases:
- Auto-format code after every file edit
- Run linting after code changes
- Update a log file with what was changed
SessionStart
When it fires: Once, when a Claude Code session begins.
Why it matters: This is your setup moment. Use it to initialize your environment, load configuration, or display a welcome message.
Example use cases:
- Load environment variables from a
.envfile - Check that required tools are installed
- Display project-specific reminders
SessionEnd
When it fires: Once, when a Claude Code session ends (you type /exit or close the terminal).
Why it matters: This is your cleanup moment. Use it to save state, send a summary, or clean up temporary files.
Example use cases:
- Save a session summary to a file
- Clean up temporary files created during the session
- Send a notification that the session ended
Notification
When it fires: When Claude wants to notify you about something — typically when a long-running task completes or something needs your attention.
Why it matters: You can customize how notifications are delivered. Instead of (or in addition to) Claude's default notification, your hook can send a desktop notification, play a sound, or send a message to Slack.
Example use cases:
- Send a desktop toast notification on Windows
- Play a sound when a task finishes
- Post a message to a Slack channel
Stop
When it fires: When Claude decides it has finished responding to your request (before SessionEnd).
Why it matters: This fires at the end of each response cycle, not just when the session ends. You can use it to run checks after Claude finishes a block of work.
Example use cases:
- Run a test suite after Claude finishes making changes
- Generate a summary of what changed
PreCompact and PostCompact
When they fire: When Claude's context window is getting full and needs to be compacted (summarized to free up space). PreCompact fires before compaction, PostCompact fires after.
Why they matter: Compaction is when Claude summarizes the conversation to make room for more context. You can use these hooks to preserve important information or reload context after compaction.
Example use cases:
- Save the current conversation state before compaction
- Reload important context after compaction
- Log when compaction happens
Choosing the Right Event
Use this guide to pick the right event for your hook:
| I want to... | Use this event |
|---|---|
| Block or inspect tool calls before they run | PreToolUse |
| React to what a tool just did (format, lint) | PostToolUse |
| Set up the environment at the start | SessionStart |
| Clean up when the session ends | SessionEnd |
| Customize notification delivery | Notification |
| Run checks after Claude finishes responding | Stop |
| Handle context compaction | PreCompact / PostCompact |
If you are just getting started with hooks, PostToolUse is the most immediately useful event. It lets you auto-format code after every edit, which is a visible and practical improvement to your workflow.
Try It Yourself
You do not need to configure any hooks yet (that is next lesson). For now, think about your current workflow and identify where hooks could help:
- Think about something you do manually every time after Claude edits code (like running a formatter or linter). That is a PostToolUse hook.
- Think about something you always do at the start of a Claude session (like setting environment variables). That is a SessionStart hook.
- Think about files Claude should never touch. That is a PreToolUse hook.
Write down your answers — you will implement at least one of them in the upcoming lessons.
What You Learned
- Claude Code has eight hookable events: PreToolUse, PostToolUse, SessionStart, SessionEnd, Notification, Stop, PreCompact, and PostCompact
- PreToolUse fires before a tool runs and can block the action
- PostToolUse fires after a tool runs and is ideal for auto-formatting and linting
- SessionStart and SessionEnd handle setup and cleanup
- Notification lets you customize how Claude alerts you
- Stop fires when Claude finishes a response cycle
- PreCompact/PostCompact let you handle context window compaction
How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.