Hooks are event-driven automation for Claude Code that execute shell commands or LLM prompts in response to tool usage, session events, and user interactions. This skill teaches you how to create, configure, and debug hooks for validating commands, automating workflows, injecting context, and implementing custom completion criteria.
Hooks provide programmatic control over Claude's behavior without modifying core code, enabling project-specific automation, safety checks, and workflow customization.
Hooks are shell commands or LLM-evaluated prompts that execute in response to Claude Code events. They operate within an event hierarchy: events (PreToolUse, PostToolUse, Stop, etc.) trigger matchers (tool patterns) which fire hooks (commands or prompts). Hooks can block actions, modify tool inputs, inject context, or simply observe and log Claude's operations.
- Create hooks config file:
- Project: .claude/hooks.json
- User: ~/.claude/hooks.json
- Choose hook event (when it fires)
- Choose hook type (command or prompt)
- Configure matcher (which tools trigger it)
- Test with
claude --debug
Log all bash commands:
.claude/hooks.json:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \\\"No description\\\")\"' >> ~/.claude/bash-log.txt"
}
]
}
]
}
}
```
This hook:
- Fires before (
PreToolUse) every Bash tool use - Executes a
command (not an LLM prompt) - Logs command + description to a file
| Event | When it fires | Can block? |
|-------|---------------|------------|
| PreToolUse | Before tool execution | Yes |
| PostToolUse | After tool execution | No |
| UserPromptSubmit | User submits a prompt | Yes |
| Stop | Claude attempts to stop | Yes |
| SubagentStop | Subagent attempts to stop | Yes |
| SessionStart | Session begins | No |
| SessionEnd | Session ends | No |
| PreCompact | Before context compaction | Yes |
| Notification | Claude needs input | No |
Blocking hooks can return "decision": "block" to prevent the action. See [references/hook-types.md](references/hook-types.md) for detailed use cases.
Type: Executes a shell command
Use when:
- Simple validation (check file exists)
- Logging (append to file)
- External tools (formatters, linters)
- Desktop notifications
Input: JSON via stdin
Output: JSON via stdout (optional)
```json
{
"type": "command",
"command": "/path/to/script.sh",
"timeout": 30000
}
```
Type: LLM evaluates a prompt
Use when:
- Complex decision logic
- Natural language validation
- Context-aware checks
- Reasoning required
Input: Prompt with $ARGUMENTS placeholder
Output: JSON with decision and reason
```json
{
"type": "prompt",
"prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}
```
Matchers filter which tools trigger the hook:
```json
{
"matcher": "Bash", // Exact match
"matcher": "Write|Edit", // Multiple tools (regex OR)
"matcher": "mcp__.*", // All MCP tools
"matcher": "mcp__memory__.*" // Specific MCP server
}
```
No matcher: Hook fires for all tools
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [...] // No matcher - fires on every user prompt
}
]
}
}
```
Hooks receive JSON via stdin with session info, current directory, and event-specific data. Blocking hooks can return JSON to approve/block actions or modify inputs.
Example output (blocking hooks):
```json
{
"decision": "approve" | "block",
"reason": "Why this decision was made"
}
```
See [references/input-output-schemas.md](references/input-output-schemas.md) for complete schemas for each hook type.
Available in hook commands:
| Variable | Value |
|----------|-------|
| $CLAUDE_PROJECT_DIR | Project root directory |
| ${CLAUDE_PLUGIN_ROOT} | Plugin directory (plugin hooks only) |
| $ARGUMENTS | Hook input JSON (prompt hooks only) |
Example:
```json
{
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
}
```
Desktop notification when input needed:
```json
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
}
]
}
]
}
}
```
Block destructive git commands:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}
]
}
]
}
}
```
Auto-format code after edits:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "prettier --write $CLAUDE_PROJECT_DIR",
"timeout": 10000
}
]
}
]
}
}
```
Add context at session start:
```json
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
}
]
}
]
}
}
```
Always test hooks with the debug flag:
```bash
claude --debug
```
This shows which hooks matched, command execution, and output. See [references/troubleshooting.md](references/troubleshooting.md) for common issues and solutions.
Hook types and events: [references/hook-types.md](references/hook-types.md)
- Complete list of hook events
- When each event fires
- Input/output schemas for each
- Blocking vs non-blocking hooks
Command vs Prompt hooks: [references/command-vs-prompt.md](references/command-vs-prompt.md)
- Decision tree: which type to use
- Command hook patterns and examples
- Prompt hook patterns and examples
- Performance considerations
Matchers and patterns: [references/matchers.md](references/matchers.md)
- Regex patterns for tool matching
- MCP tool matching patterns
- Multiple tool matching
- Debugging matcher issues
Input/Output schemas: [references/input-output-schemas.md](references/input-output-schemas.md)
- Complete schema for each hook type
- Field descriptions and types
- Hook-specific output fields
- Example JSON for each event
Working examples: [references/examples.md](references/examples.md)
- Desktop notifications
- Command validation
- Auto-formatting workflows
- Logging and audit trails
- Stop logic patterns
- Session context injection
Troubleshooting: [references/troubleshooting.md](references/troubleshooting.md)
- Hooks not triggering
- Command execution failures
- Prompt hook issues
- Permission problems
- Timeout handling
- Debug workflow
Creating Installable Hooks for claude-code-toolkit
When creating hooks for distribution via the toolkit, use this structure:
```
hooks/
βββ my-hook/
βββ README.md # Documentation
βββ install.sh # Standalone installer
βββ settings-template.json # Hook configuration to merge
βββ toggle.sh # Optional: on/off toggle script
```
settings-template.json (hook configuration):
```json
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "your-hook-command-here"
}
]
}
]
}
}
```
install.sh (standalone installer):
```bash
#!/bin/bash
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CLAUDE_DIR="$HOME/.claude"
TEMPLATE_FILE="$SCRIPT_DIR/settings-template.json"
# Check dependencies
command -v jq &>/dev/null || { echo "jq required"; exit 1; }
# Create settings if missing
mkdir -p "$CLAUDE_DIR"
[ -f "$CLAUDE_DIR/settings.json" ] || echo '{}' > "$CLAUDE_DIR/settings.json"
# Backup and merge
cp "$CLAUDE_DIR/settings.json" "$CLAUDE_DIR/settings.json.bak"
jq -s '.[0] * .[1]' "$CLAUDE_DIR/settings.json" "$TEMPLATE_FILE" > /tmp/merged.json
mv /tmp/merged.json "$CLAUDE_DIR/settings.json"
echo "Hook installed"
```
REQUIRED: Update root installers:
After creating a new hook, you MUST update both install-linux.sh and install-mac.sh:
- Add install function:
```bash
install_my_hook() {
local INSTALL_SCRIPT="$SCRIPT_DIR/hooks/my-hook/install.sh"
[ -f "$INSTALL_SCRIPT" ] || { echo "Hook not found"; return; }
bash "$INSTALL_SCRIPT"
}
```
- Add to "install all" section:
```bash
echo -e "${BLUE}My Hook (description):${NC}"
install_my_hook
```
- Add to "select by folder" section:
```bash
echo
echo -e "${BLUE}βββ My Hook βββ${NC}"
echo -e "${DIM}Brief description of what the hook does${NC}"
echo -n "Install my-hook? (y/n): "
read -r choice
[[ "$choice" =~ ^[Yy]$ ]] && install_my_hook
```
Examples in toolkit:
hooks/concise-mode/ - UserPromptSubmit hook with togglehooks/damage-control/ - PreToolUse hooks with Python scripts
Critical safety requirements:
- Infinite loop prevention: Check
stop_hook_active flag in Stop hooks to prevent recursive triggering - Timeout configuration: Set reasonable timeouts (default: 60s) to prevent hanging
- Permission validation: Ensure hook scripts have executable permissions (
chmod +x) - Path safety: Use absolute paths with
$CLAUDE_PROJECT_DIR to avoid path injection - JSON validation: Validate hook config with
jq before use to catch syntax errors - Selective blocking: Be conservative with blocking hooks to avoid workflow disruption
Testing protocol:
```bash
# Always test with debug flag first
claude --debug
# Validate JSON config
jq . .claude/hooks.json
```
A working hook configuration has:
- Valid JSON in
.claude/hooks.json (validated with jq) - Appropriate hook event selected for the use case
- Correct matcher pattern that matches target tools
- Command or prompt that executes without errors
- Proper output schema (decision/reason for blocking hooks)
- Tested with
--debug flag showing expected behavior - No infinite loops in Stop hooks (checks
stop_hook_active flag) - Reasonable timeout set (especially for external commands)
- Executable permissions on script files if using file paths
|