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.
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.
| name | hook-templates |
|---|---|
| description | 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. |
| 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 2for blocking (not exit 1)? - Debug to stderr (
>&2), output to stdout? - New session after settings.json change?
Common Mistakes
- Missing nested
hooksarray - Missing
"type": "command" - Using exit 1 instead of exit 2 for blocking
- Object matcher (not supported) - use script parsing instead