hooks

Hook Development Rules

⭐2.2kstars🔀157forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a standardized framework and architectural pattern for developing custom hooks within the Claude agent environment. It establishes a robust Shell-to-TypeScript workflow, allowing developers to intercept and manage critical agent events such as tool execution, prompt submission, and session lifecycle. By implementing these development rules, users can extend Claude's functionality with custom logic, enforce operational guardrails, and automate complex environment setups.

Use Cases

  • Implementing Guardrails: Use the PreToolUse hook to intercept tool calls, validate parameters, and block unauthorized or unsafe commands before execution.
  • Automated Environment Setup: Leverage the SessionStart hook to automatically configure environment variables, pull latest git changes, or initialize databases when a project session begins.
  • Custom Audit Logging: Utilize PostToolUse hooks to capture the output of agent actions and send them to external monitoring tools or databases for compliance and debugging.
  • Context Enrichment: Use the UserPromptSubmit hook to automatically append project-specific documentation or style guides to every user request, ensuring the agent remains aligned with project standards.
  • State Management: Employ PreCompact hooks to save essential session state or summarize progress before the agent's context window is compressed.
namehooks
descriptionHook Development Rules
user-invocablefalse

Hook Development Rules

When working with files in .claude/hooks/:

Pattern

Shell wrapper (.sh) → TypeScript (.ts) via npx tsx

Shell Wrapper Template

#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | npx tsx <handler>.ts

TypeScript Handler Pattern

interface HookInput {
  // Event-specific fields
}

async function main() {
  const input: HookInput = JSON.parse(await readStdin());

  // Process input

  const output = {
    result: 'continue',  // or 'block'
    message: 'Optional system reminder'
  };

  console.log(JSON.stringify(output));
}

Hook Events

  • PreToolUse - Before tool execution (can block)
  • PostToolUse - After tool execution
  • UserPromptSubmit - Before processing user prompt
  • PreCompact - Before context compaction
  • SessionStart - On session start/resume/compact
  • Stop - When agent finishes

Testing

Test hooks manually:

echo '{"type": "resume"}' | .claude/hooks/session-start-continuity.sh

Registration

Add hooks to .claude/settings.json:

{
  "hooks": {
    "EventName": [{
      "matcher": ["pattern"],  // Optional
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/hook.sh"
      }]
    }]
  }
}