session-hooks-template

Session Hooks Template

A template for creating Claude Code session hook plugins. Fork this repo to build your own custom session behaviors.

What Are Session Hooks?

Claude Code plugins can hook into various session events to:

• Inject context into conversations
• Block or modify tool calls
• Enforce conditions before task completion
• Track state across the session
• Trigger external actions based on events

This template provides ready-to-use hook scripts for all major hook types with extensive documentation and examples.

Quick Start

1. Fork/Clone this template

   # Clone the template
   git clone https://github.com/johnlindquist/claude-session-hooks-template.git my-plugin
   cd my-plugin
   
   # Install dependencies
   bun install
   

2. Customize the plugin

   • Edit package.json and .claude-plugin/plugin.json with your plugin name
   • Modify the hook scripts in scripts/ for your use case
   • Update STATE_FILE_PREFIX in src/state.ts

3. Install and test

   # Install as local plugin
   claude plugin install . --scope local
   
   # Test your changes
   claude  # Start a session and try your hooks
   

Available Hooks

Hook	File	When It Fires
SessionStart	scripts/SessionStart.ts	When a session begins
UserPromptSubmit	scripts/UserPromptSubmit.ts	On every user prompt
Stop	scripts/Stop.ts	When Claude tries to stop
PreToolUse	scripts/PreToolUse.ts	Before any tool executes
PostToolUse	scripts/PostToolUse.ts	After a tool completes

Hook Data Flow

┌──────────────────────────────────────────────────────────────┐
│                      Claude Code Session                      │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  SessionStart ─────► User types prompt                       │
│                           │                                   │
│                           ▼                                   │
│                   UserPromptSubmit ◄───── Inject context?     │
│                           │                                   │
│                           ▼                                   │
│                   Claude processes...                         │
│                           │                                   │
│                   ┌───────┴───────┐                          │
│                   ▼               ▼                          │
│              PreToolUse      (No tools)                      │
│                   │               │                          │
│                   ▼               │                          │
│              Tool executes        │                          │
│                   │               │                          │
│                   ▼               │                          │
│              PostToolUse          │                          │
│                   │               │                          │
│                   └───────┬───────┘                          │
│                           ▼                                   │
│                      Stop ◄───── Block? Allow?               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Hook Details

SessionStart

File: scripts/SessionStart.ts

Fires when a Claude Code session begins. Use it to:

• Initialize session state
• Load configuration
• Inject initial context

Input fields:

• session_id - Unique session identifier
• source - Why session started: "startup" | "resume" | "clear" | "compact"
• cwd - Current working directory

Output options:

• additionalContext - Text to inject into the conversation

UserPromptSubmit

File: scripts/UserPromptSubmit.ts

Fires on every user prompt. Use it to:

• Analyze prompts for keywords/patterns
• Inject context based on prompt content
• Track prompt history

Input fields:

• session_id - Unique session identifier
• prompt - The user's prompt text
• cwd - Current working directory

Output options:

• additionalContext - Text to inject after the prompt

Stop

File: scripts/Stop.ts

Fires when Claude attempts to stop. Use it to:

• Block stopping until conditions are met
• Require verification before completion
• Implement quality gates

Input fields:

• session_id - Unique session identifier
• stop_hook_active - True if another hook already blocked this stop

Output options:

• decision - "block" to prevent stopping, undefined to allow
• reason - Message explaining why stop is blocked

Important: Always check stop_hook_active and implement a safety valve (max denials) to prevent infinite loops.

PreToolUse

File: scripts/PreToolUse.ts