hooks
/hooks
Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.
- Author
- CaptainCrouton89 ↗
- Repository
- crouton-kit ↗
- Licence
- GPL-3.0
- Last repository change
- 02.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.10.2026, without references to retired models or APIs.
GPL-3.0, otwarta.
What it does and when to use it
Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.
Original author description
Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.
How it works
- When to Use Hooks vs Other Tools
- Hook Events
- Handler Types
- Decision Control
- Matchers
- Skill- and Agent-Scoped Hooks
- Common Patterns
- Best Practices
SKILL.md preview
---
name: hooks
description: Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.
user-invocable: false
paths:
- "**/hooks.json"
- "**/hooks/**/*.py"
- "**/hooks/**/*.sh"
- "**/hooks/**/*.mjs"
- "**/hooks/**/*.js"
- "**/hooks/**/*.ts"
---
# Claude Code Hooks
Hooks are deterministic handlers that fire at lifecycle events. Unlike instructions, hooks **cannot be ignored** — they block, inject, or modify at the system level.
## When to Use Hooks vs Other Tools
- **Hooks**: Must happen every time, no exceptions (guardrails, formatting, enforcement)
- **Rules/CLAUDE.md**: Advisory guidance Claude should follow (conventions, preferences)
- **Skills**: On-demand reference material (knowledge, methodology)
## Hook Events
Hooks fire at three points in execution: before the user or agent acts (`UserPromptSubmit`, `PreToolUse`), after the system acts (`PostToolUse`, `Stop`), and during agent lifecycle transitions (`SubagentStart`, `TaskCompleted`). Session bookend events (`SessionStart`, `SessionEnd`) handle setup and teardown. See [reference.md](reference.md) for the full event list with blocking/injection capabilities per event.
## Handler Types
Pick based on how complex the decision is:
| Handler | Use when... |
|---------|-------------|
| **command** | Logic is deterministic — regex check, file exists, env var set. Fastest. |
| **prompt** | Decision requires judgment but no file access — "is this prompt asking for secrets?" |
| **agent** | Decision requires investigation — read files, run commands, check state. |
| **http** | Hook logic lives outside the machine — shared enforcement service, cross-team policy. |
Default to `command`. Escalate to `prompt` only when a shell script can't encode the judgment. Use `agent` sparingly — it spawns a subagent and adds real latency.
## Decision Control
All hook output must be wrapped in `hookSpecificOutput` with the matching `hookEventName`. **`hookEventName` is required** — without it, Claude Code silently drops the payload.
```json
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"additionalContext": "injected text"
}
}
```
See [reference.md](reference.md) for the full per-event return value spec (`permissionDecision`, `updatedInput`, `decision: "block"`, etc.).
## Matchers
Use `|` to target multiple tools: `"matcher": "Write|Edit|MultiEdit"`. MCP tools match as `mcp__servername__toolname`. Omit matcher to catch all tools for that event.
See [reference.md](reference.md) for full matcher syntax including SessionStart variants.
## Skill- and Agent-Scoped Hooks
Hooks can be declared in `SKILL.md` or agent frontmatter to scope them to that skill/agent only — useful for guardrails that shouldn't apply globally. Uses the same matcher/handler format as `hooks.json`, nested under `hooks:` in frontmatter. See [reference.md](reference.md) for a full example.
## Common Patterns
See [patterns.md](patterns.md) for comprehensive examples organized by category:
- Guardrails and enforcement
- Context injection
- Quality gates (auto-format, lint, test)
- Notifications and alerts
- Logging and auditing
- Auto-approval workflows
- Input modification and sandboxing
- Git workflow automation
- Session management
- Agent team coordination
## Best Practices
- **Async for slow operations**: Set `"async": true` for hooks that shouldn't block (tests, notifications)
- **Timeouts**: Default is 60s for sync hooks. Set explicit timeouts for fast hooks.
- **Idempotency**: Hooks may fire multiple times. Guard against duplicate processing.
- **Stop hook loops**: Always check `stop_hook_active` to prevent infinite continuation loops.
- **Minimal hooks.json**: One concern per hook. Compose multiple small hooks rather than one monolith.
Files in this package (3)
- SKILL.md 4 KB
- patterns.md 5 KB
- reference.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · CaptainCrouton89/crouton-kit | 100 | GPL-3.0 |
| ai-answer/contentrepurposesystem | 100 | MIT |
| stxrmik/antigravity-plus | 100 | MIT |
| nimadorostkar/Claude-Skills-collection | 100 | MIT |
| opus-pro/reel-runbook | 100 | MIT |
| Rohitjangid2704/Tessa | 90 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version b66d3e775780 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90Creating Hooks
Build event-driven hooks in Claude Code for validation, setup, and automation. Use when you need to validate inputs, check environment state, or automate tasks at specific lifecycle events. - 95hook-dev
Use this skill when creating or refining Claude Code hooks. Hooks are shell commands that execute at specific lifecycle events (tool use, prompt submit, notifications, session events). Helps design event handlers for notifications, formatting, logging, feedback, and permission… - 100claude-code-hooks
Claude Code hooks configuration patterns, event types, validation scripts, and decision control for automating workflows and integrating external tools. This skill should be used when creating hooks, validating tool usage, automating workflows, or integrating external tools with Claude Code. - 100error-handling
Debug and recover from agent team errors including common errors, hooks for quality gates, known limitations, and recovery strategies. Use when encountering team errors, enforcing quality gates with hooks, understanding limitations, or debugging agent issues. - 95creating-claude-hooks
Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure - 95creating-claude-hooks
Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure