Agent skill
claude-code-hooks
Guide for implementing Claude Code hooks - automated scripts that execute at specific workflow points. Use when building hooks, understanding hook events, or troubleshooting hook configuration.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/claude-code-hooks-hgeldenhuys-claude-hooks-sdk
SKILL.md
Claude Code Hooks Implementation Guide
Implement automated hooks that execute bash commands or TypeScript scripts in response to Claude Code events.
Quick Reference
9 Available Hook Events
- PreToolUse - Before tool execution (validation, blocking)
- PostToolUse - After tool success (formatting, testing)
- Notification - On Claude notifications
- UserPromptSubmit - Before processing user input (context injection)
- Stop - When main agent finishes responding
- SubagentStop - When subagent completes
- PreCompact - Before context compaction
- SessionStart - Session begins
- SessionEnd - Session ends
Hook Input (stdin JSON)
json
{
"session_id": "...",
"transcript_path": "...",
"cwd": "/current/working/dir",
"permission_mode": "default",
"hook_event_name": "PostToolUse",
"tool_name": "Write",
"tool_input": {"file_path": "...", "content": "..."},
"tool_response": "..."
}
Hook Output Mechanisms
Exit Codes:
0- Success (stdout → transcript, or context if UserPromptSubmit)2- Blocking error (stderr → Claude feedback)- Other - Non-blocking error (shown to user)
JSON Output (stdout):
json
{
"continue": true,
"stopReason": "optional message",
"suppressOutput": true,
"decision": "allow|deny|ask",
"hookSpecificOutput": {}
}
Recommended: Use claude-hooks-sdk for TypeScript
For TypeScript hooks, use the SDK for type safety and utilities:
bash
bun add claude-hooks-sdk
typescript
#!/usr/bin/env bun
import { HookManager, success, block, createLogger } from 'claude-hooks-sdk';
const logger = createLogger('my-hook');
const manager = new HookManager({
logEvents: true,
clientId: 'my-hook',
trackEdits: true,
});
manager.onPreToolUse(async (input) => {
if (input.tool_name === 'Bash' && input.tool_input.command.includes('rm -rf /')) {
logger.warn('Blocked dangerous command');
return block('Dangerous command blocked');
}
return success();
});
manager.run();
Common Use Cases
1. Code Formatting (PostToolUse)
Configuration (.claude/settings.json):
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh"
}
]
}
]
}
}
Script (.claude/hooks/format-code.sh):
bash
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
if [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx)$ ]]; then
npx prettier --write "$FILE_PATH" 2>&1
echo "✓ Formatted: $FILE_PATH"
fi
exit 0
2. Security Validation (PreToolUse)
bash
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
# Block dangerous patterns
if [[ "$COMMAND" =~ (rm\ -rf\ /|\.\./) ]]; then
echo '{"decision": "deny", "continue": false}' | jq
echo "❌ Blocked: Dangerous command" >&2
exit 2
fi
echo '{"decision": "allow", "continue": true}' | jq
exit 0
3. Context Injection (UserPromptSubmit)
Using SDK (recommended):
typescript
#!/usr/bin/env bun
import { createUserPromptSubmitHook } from 'claude-hooks-sdk';
// ONE LINE - injects session ID and name into Claude's context
createUserPromptSubmitHook();
4. Environment Setup (SessionStart)
bash
#!/bin/bash
if [ ! -d "node_modules" ]; then
bun install
fi
if [ -n "$CLAUDE_ENV_FILE" ]; then
echo "export NODE_ENV=development" >> "$CLAUDE_ENV_FILE"
fi
echo "✓ Environment ready"
exit 0
Configuration Patterns
Project-Specific Hooks
Store in .claude/settings.json (project root):
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{"type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"}
]
}
]
}
}
Global Hooks
Store in ~/.claude/settings.json (user home).
Troubleshooting
Hook Not Executing
- Check matcher pattern (case-sensitive)
- Verify script permissions:
chmod +x script.sh - Enable debug mode:
claude --debug
Hook Blocking Execution
- Exit code 2 blocks, other codes don't
{"decision": "deny"}blocks PreToolUse
Resources
Didn't find tool you were looking for?