claude-session-hooks-template AGENTS.md

AI Agent Instructions

This is a template repository for building Claude Code session hook plugins. When working with this codebase, your goal is to help users create custom session behaviors.

Understanding This Template

What This Template Provides

1. Five hook scripts in scripts/:

   • SessionStart.ts - Fires when a session begins
   • UserPromptSubmit.ts - Fires on every user prompt
   • Stop.ts - Fires when Claude tries to stop
   • PreToolUse.ts - Fires before any tool executes
   • PostToolUse.ts - Fires after a tool completes

2. Utilities in src/:

   • state.ts - Persist data across hook invocations
   • utils.ts - Common helper functions

3. Configuration in hooks/hooks.json and .claude-plugin/plugin.json

How Hooks Work

Hooks are TypeScript scripts that:

1. Receive JSON input via stdin
2. Process the input
3. Output JSON to stdout

Each hook has access to:

• session_id - Unique identifier for the session
• cwd - Current working directory
• Hook-specific data (prompt text, tool name, etc.)

Common User Requests

"I want to [action] when the user [trigger]"

Pattern: Use UserPromptSubmit hook

Example: "Remind the agent to run tests when the user mentions 'deploy'"

// In scripts/UserPromptSubmit.ts
if (prompt.toLowerCase().includes('deploy')) {
  contextMessages.push('<reminder>Run tests before deploying!</reminder>');
}

"I want to block [tool] when [condition]"

Pattern: Use PreToolUse hook

Example: "Block Bash commands containing 'rm -rf'"

// In scripts/PreToolUse.ts
if (tool_name === 'Bash') {
  const command = (tool_input as { command?: string }).command || '';
  if (command.includes('rm -rf')) {
    return denyTool('Dangerous command blocked');
  }
}

"I want to require [condition] before completing"

Pattern: Use Stop hook

Example: "Require tests to pass before allowing stop"

// In scripts/Stop.ts
const state = await getState<MyState>(session_id);
if (state?.testsRequired && !state.testsPassed) {
  return blockStop('Tests must pass before completing');
}