hook-templates

Comprehensive Claude Code hook patterns for automation, state management, and external integration. Use when implementing hooks for validation, workflow gates, MCP integration, or state machines.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive library of production-tested hook patterns designed for Claude Code (v1.0.40+). It enables developers to implement sophisticated automation, state management, and external integrations by leveraging lifecycle events like PreToolUse and PostToolUse. These templates facilitate the creation of workflow gates, context injection, and reliable agent orchestration, ensuring higher success rates in complex task execution.

Use Cases

  • Workflow Guardrails: Implementing safety gates to block dangerous terminal commands or enforce prerequisites before a tool is executed.
  • Automated Side Effects: Triggering post-tool actions such as automatic code formatting, linting, or git commits immediately after a file modification.
  • State & Context Management: Using hooks to track workflow phases, manage session-specific state files, or inject project context at the start of a session.
  • External System Integration: Connecting Claude to external APIs, MCP (Model Context Protocol) servers, or WebSockets to extend the agent's capabilities with real-time data.
  • Agent Orchestration: Forcing the evaluation of specific skills or routing tasks to specialized sub-agents via the Task tool with high reliability.
namehook-templates
descriptionComprehensive Claude Code hook patterns for automation, state management, and external integration. Use when implementing hooks for validation, workflow gates, MCP integration, or state machines.
allowed-tools["Read", "Write", "Bash", "Grep", "Glob"]

Hook Patterns

Production-tested patterns for Claude Code hooks (1.0.40+).

Hook Roles (Beyond Just Validation)

Role Hook Event Example
Gate PreToolUse Block dangerous commands, require prerequisites
Side Effect PostToolUse Auto-format, auto-commit, lint
State Manager PostToolUse Create/delete state files, track workflow phase
External Integrator Any MCP calls, HTTP APIs, WebSocket
Context Injector SessionStart Load project context, activate services

Event Reference

Event Trigger Can Block Use For
SessionStart Session begins No Context loading, service activation
UserPromptSubmit User sends message Yes Prompt validation, skill suggestion
PreToolUse Before tool Yes Validation, workflow gates
PostToolUse After tool No State updates, side effects
Stop Claude stops Yes Quality gates, cleanup
SubagentStop Subagent stops Yes Subagent quality gates

Exit Codes

Code PreToolUse/Stop Others
0 Allow Continue
2 Block (stderr→Claude) Logged
1, 3+ Block Logged

JSON Response (Advanced)

{
  "decision": "approve|block",
  "reason": "Shown to user/Claude",
  "continue": true,
  "suppressOutput": false
}

Quick Registration

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "script.sh", "timeout": 5 }]
    }]
  }
}

Pattern Selection

Need Pattern Reference
Force skill/agent activation Orchestration orchestration-templates.md
Block dangerous actions Gate Pattern gate-patterns.md
Auto-format/lint/commit Side Effect Pattern side-effect-patterns.md
Full working examples Examples full-examples.md

Orchestration Patterns (NEW)

Hook-based skill/agent activation with reliability stats:

Pattern Success Use Case
Forced Evaluation 84% Force Claude to evaluate and use skills
Agent Router 100% Route to plugin agents via Task tool
Context Injection 100% Load project context at session start

See orchestration-templates.md for templates.

Debugging

Common issues and solutions in debugging-guide.md.

Quick checklist:

  • Hook executable? (chmod +x)
  • Using INPUT=$(cat) to read stdin?
  • Using exit 2 for blocking (not exit 1)?
  • Debug to stderr (>&2), output to stdout?
  • New session after settings.json change?

Common Mistakes

  • Missing nested hooks array
  • Missing "type": "command"
  • Using exit 1 instead of exit 2 for blocking
  • Object matcher (not supported) - use script parsing instead