# The 20 Available Hook Types in PAI: Complete Event-Driven Automation Guide

> Discover the 20 hook types in PAI and their triggers. Automate Claude Code sessions with custom TypeScript or Python for event-driven workflows. Learn more now.

- Repository: [Daniel Miessler 🛡️/Personal_AI_Infrastructure](https://github.com/danielmiessler/personal_ai_infrastructure)
- Tags: tutorial
- Published: 2026-02-16

---

**Personal AI Infrastructure (PAI) provides 7 core hook events that trigger 20 built-in automation scripts, enabling custom TypeScript or Python execution at specific moments in Claude Code sessions.**

Daniel Miessler’s [Personal AI Infrastructure](https://github.com/danielmiessler/Personal_AI_Infrastructure) implements an event-driven hook system that intercepts session lifecycle moments to run custom logic. While PAI defines **7 distinct hook events** (the trigger conditions), the framework ships with **20 individual hook scripts** distributed across those events, providing ready-made automation for greetings, security validation, learning capture, and tool orchestration.

## The 7 Core Hook Events and Their Trigger Conditions

PAI hook events fire at specific, immutable moments in the Claude Code execution flow. Each event represents a **hook type** that determines when associated scripts execute.

### SessionStart

**Trigger condition:** Fires the instant a new Claude Code session (conversation) is created, before any user input is processed.

This event initializes the conversational context. Built-in hooks running here include [`StartupGreeting.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/StartupGreeting.hook.ts), [`LoadContext.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/LoadContext.hook.ts), and [`CheckVersion.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/CheckVersion.hook.ts).

### SessionEnd

**Trigger condition:** Activates when the session is explicitly terminated, such as when the user runs `:exit` or the process receives a shutdown signal.

This event handles cleanup and learning persistence. Hooks include [`WorkCompletionLearning.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/WorkCompletionLearning.hook.ts), [`SessionSummary.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SessionSummary.hook.ts), [`RelationshipMemory.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RelationshipMemory.hook.ts), [`UpdateCounts.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/UpdateCounts.hook.ts), and [`IntegrityCheck.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/IntegrityCheck.hook.ts).

### UserPromptSubmit

**Trigger condition:** Executes immediately after the user submits a new prompt but before Claude begins processing the request.

This event captures user intent and prepares auxiliary systems. Hooks include [`RatingCapture.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RatingCapture.hook.ts), [`AutoWorkCreation.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AutoWorkCreation.hook.ts), [`UpdateTabTitle.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/UpdateTabTitle.hook.ts), and [`SessionAutoName.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SessionAutoName.hook.ts).

### Stop

**Trigger condition:** Fires after the main agent (the “DA IDENTITY”) finishes rendering a response and control returns to the user.

This event coordinates post-response actions. The primary hook is [`StopOrchestrator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/StopOrchestrator.hook.ts), which delegates to five sub-handlers: [`VoiceNotification.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/VoiceNotification.ts), [`TabState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/TabState.ts), [`RebuildSkill.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RebuildSkill.ts), [`AlgorithmEnrichment.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AlgorithmEnrichment.ts), and [`DocCrossRefIntegrity.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/DocCrossRefIntegrity.ts).

### PreToolUse

**Trigger condition:** Executes immediately before Claude Code runs any tool, including Bash, Edit, Write, Read, AskUserQuestion, Task, or Skill.

This event provides security and context gating. Hooks include [`VoiceGate.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/VoiceGate.hook.ts), [`SecurityValidator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SecurityValidator.hook.ts), [`SetQuestionTab.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SetQuestionTab.hook.ts), [`AgentExecutionGuard.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AgentExecutionGuard.hook.ts), and [`SkillGuard.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SkillGuard.hook.ts).

### PostToolUse

**Trigger condition:** Activates immediately after a tool finishes executing and returns results to the agent.

This event captures execution outcomes for learning algorithms. Hooks include [`QuestionAnswered.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/QuestionAnswered.hook.ts) and [`AlgorithmTracker.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AlgorithmTracker.hook.ts).

### PreCompact

**Trigger condition:** Fires just before Claude Code compacts the conversation context during long-running chats to manage token limits.

Currently, no built-in hooks are configured for this event in the default release, though the event type is available for custom implementations.

## The 20 Built-In Hook Scripts by Event

PAI distributes **20 distinct hook scripts** across the seven event types. The following table maps each script to its triggering event and primary function:

| Hook Script | Event | Function |
|-------------|-------|----------|
| [`StartupGreeting.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/StartupGreeting.hook.ts) | SessionStart | Displays personalized welcome message based on identity config |
| [`LoadContext.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/LoadContext.hook.ts) | SessionStart | Loads persistent context files into session memory |
| [`CheckVersion.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/CheckVersion.hook.ts) | SessionStart | Validates PAI version compatibility |
| [`WorkCompletionLearning.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/WorkCompletionLearning.hook.ts) | SessionEnd | Extracts learning from completed work units |
| [`SessionSummary.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SessionSummary.hook.ts) | SessionEnd | Generates conversation summaries for long-term memory |
| [`RelationshipMemory.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RelationshipMemory.hook.ts) | SessionEnd | Updates relationship context between user and DA |
| [`UpdateCounts.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/UpdateCounts.hook.ts) | SessionEnd | Persists usage statistics and token counts |
| [`IntegrityCheck.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/IntegrityCheck.hook.ts) | SessionEnd | Validates file system integrity of PAI directories |
| [`RatingCapture.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RatingCapture.hook.ts) | UserPromptSubmit | Captures implicit quality signals from prompt patterns |
| [`AutoWorkCreation.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AutoWorkCreation.hook.ts) | UserPromptSubmit | Automatically creates work items from prompt intent |
| [`UpdateTabTitle.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/UpdateTabTitle.hook.ts) | UserPromptSubmit | Updates terminal tab titles with session context |
| [`SessionAutoName.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SessionAutoName.hook.ts) | UserPromptSubmit | Generates semantic names for unnamed sessions |
| [`StopOrchestrator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/StopOrchestrator.hook.ts) | Stop | Coordinates post-response actions (delegates to 5 sub-modules) |
| [`VoiceGate.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/VoiceGate.hook.ts) | PreToolUse | Blocks voice notifications for background agents |
| [`SecurityValidator.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SecurityValidator.hook.ts) | PreToolUse | Validates tool commands against security policies |
| [`SetQuestionTab.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SetQuestionTab.hook.ts) | PreToolUse | Configures UI state for question-asking tools |
| [`AgentExecutionGuard.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AgentExecutionGuard.hook.ts) | PreToolUse | Prevents recursive agent spawning |
| [`SkillGuard.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/SkillGuard.hook.ts) | PreToolUse | Validates skill file integrity before execution |
| [`QuestionAnswered.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/QuestionAnswered.hook.ts) | PostToolUse | Logs Q&A pairs for knowledge base building |
| [`AlgorithmTracker.hook.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AlgorithmTracker.hook.ts) | PostToolUse | Tracks algorithm execution paths for optimization |

The **StopOrchestrator** technically counts as one hook script but internally delegates to five handler modules: [`VoiceNotification.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/VoiceNotification.ts), [`TabState.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/TabState.ts), [`RebuildSkill.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/RebuildSkill.ts), [`AlgorithmEnrichment.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/AlgorithmEnrichment.ts), and [`DocCrossRefIntegrity.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/DocCrossRefIntegrity.ts).

## Configuring Hook Triggers in settings.json

Hook execution is controlled through `~/.claude/settings.json`, which maps the seven event types to ordered arrays of hook descriptors.

### Basic Configuration Structure

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${PAI_DIR}/hooks/StartupGreeting.hook.ts"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${PAI_DIR}/hooks/SecurityValidator.hook.ts"
          }
        ]
      }
    ]
  }
}

```

### Matcher Conditions

The **matcher** field filters hooks to specific tools or contexts. When present, the hook only fires if the condition matches:

- **Tool-specific matching**: `"matcher": "Bash"` restricts the hook to Bash tool invocations
- **Pattern matching**: Supports wildcards for tool name patterns
- **Absence**: No matcher means the hook fires for every instance of the event type

### Execution Order

Hooks execute **sequentially** in the order defined in the JSON array. A hook that hangs or crashes prevents subsequent hooks from running, which is why all built-in scripts exit with status 0 immediately after completing their work.

## Building Custom PAI Hooks

Custom hooks read event data from **STDIN** as JSON payloads. Each event type provides a specific schema documented in [`THEHOOKSYSTEM.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/THEHOOKSYSTEM.md).

### Example: Custom PreToolUse Hook

```typescript
#!/usr/bin/env bun
interface PreToolUsePayload {
  session_id: string
  transcript_path: string
  hook_event_name: "PreToolUse"
  tool_name: string
  tool_input: any
}

async function main() {
  const raw = await Bun.stdin.text()
  const data: PreToolUsePayload = JSON.parse(raw)
  
  // Custom logic: Log all file writes
  if (data.tool_name === "Write") {
    const { appendFileSync } = require('fs')
    const logPath = `${process.env.PAI_DIR}/hooks/logs/writes.log`
    const entry = `[${new Date().toISOString()}] ${data.tool_input.file_path}\n`
    appendFileSync(logPath, entry)
  }
  
  // Must exit cleanly
  process.exit(0)
}

main()

```

### Payload Schema by Event Type

According to [`Releases/v3.0/.claude/skills/PAI/THEHOOKSYSTEM.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/THEHOOKSYSTEM.md), each event delivers specific fields:

- **SessionStart/End**: `session_id`, `transcript_path`, `timestamp`
- **UserPromptSubmit**: Includes the `prompt` text submitted by the user
- **PreToolUse/PostToolUse**: Includes `tool_name` and `tool_input`/`tool_output`
- **Stop**: Contains the response content and token usage statistics

## Summary

- **PAI defines 7 hook event types** (SessionStart, SessionEnd, UserPromptSubmit, Stop, PreToolUse, PostToolUse, PreCompact) that serve as trigger conditions throughout the Claude Code lifecycle.
- **20 built-in hook scripts** are distributed across these events, handling automation for greetings, security validation, learning capture, and tool orchestration.
- **Trigger conditions** are defined by the event type itself (e.g., PreToolUse fires before any tool execution) and can be refined with **matcher** patterns in [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/settings.json) to filter by specific tool names.
- **Configuration** occurs in `~/.claude/settings.json`, where hooks are mapped to events and executed sequentially in the order defined.
- **Custom hooks** receive JSON payloads via STDIN and must exit with status 0 to avoid blocking subsequent automation.

## Frequently Asked Questions

### What is the difference between a hook event and a hook script in PAI?

A **hook event** (also called a hook type) is the trigger condition itself—one of the seven lifecycle moments like `SessionStart` or `PreToolUse`. A **hook script** is the executable file (TypeScript or Python) that runs when that event fires. PAI provides 7 event types but ships with 20 distinct hook scripts, meaning some events trigger multiple scripts sequentially.

### How do I prevent a specific hook from running in certain sessions?

Remove or comment out the hook descriptor from the relevant event array in `~/.claude/settings.json`. Alternatively, for tool-specific hooks, modify the **matcher** field to match only tool names you want to intercept. For example, changing `"matcher": "Bash"` to `"matcher": "Read"` ensures the hook only fires before Read tool execution, effectively disabling it for Bash commands.

### Can I write PAI hooks in Python instead of TypeScript?

Yes. While the 20 built-in hooks are implemented in TypeScript (using the Bun runtime), PAI executes any command-line executable. Python scripts can read the JSON payload from STDIN using `sys.stdin`, process the event data, and exit with status 0. Ensure your Python script includes the appropriate shebang (`#!/usr/bin/env python3`) and is executable, or invoke it explicitly via the command field in [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/settings.json).

### What happens if a hook script fails or hangs?

Hooks execute **sequentially** in the order defined in [`settings.json`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/settings.json). If a hook exits with a non-zero status or hangs indefinitely, it **blocks all subsequent hooks** in the same event group from running. PAI does not implement timeout handling by default, so a hanging hook will freeze the Claude Code session at that lifecycle point. All built-in hooks are designed to exit immediately with status 0 after completing their work to prevent this blocking behavior.