The Hook Lifecycle: Events You Can Tap Into

Hooks only help if you attach them to the right moment. Claude Code fires a fixed set of events during a session, and each one is a place you can run a command. Here is the full list and what each is good for.

The events

• PreToolUse — before Claude runs a tool. This is where you inspect or block an action before it happens.
• PostToolUse — after a tool finishes. Good for reacting to a change, like formatting a file that was just edited.
• UserPromptSubmit — when you submit a prompt, before Claude sees it.
• Stop — when Claude finishes responding. A natural place to run tests.
• SubagentStop — when a subagent finishes its work.
• SessionStart — when a session begins. Use it to load context.
• PreCompact — before the conversation is compacted.
• Notification — when Claude sends a notification, such as needing your input.

Grouping them by intent

Two of these wrap tool calls: PreToolUse runs before, PostToolUse runs after. They pair with a matcher that picks which tool triggers them.

Three track the flow of a turn or session: UserPromptSubmit, Stop, and SubagentStop.

The rest are lifecycle moments: SessionStart, PreCompact, and Notification.

Shape of the config

Every event is an array of matcher groups in settings.json:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "git status --short" }] }
    ]
  }
}

Pick the event that matches the moment you care about, and the rest of the config follows the same pattern. The following articles each take one event and build something useful with it.