Claude 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                       │
│