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.
Install this agent skill to your Project
npx add-skill https://github.com/hgeldenhuys/claude-hooks-sdk/tree/main/.claude-plugin/plugins/skill-claude-code-hooks
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)
{
"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):
{
"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:
bun add claude-hooks-sdk
#!/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):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh"
}
]
}
]
}
}
Script (.claude/hooks/format-code.sh):
#!/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)
#!/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):
#!/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)
#!/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):
{
"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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
hgeldenhuys/claude-hooks-sdk
claude-hooks-sdk
Expert guide for building Claude Code hooks using the claude-hooks-sdk npm package. Use when implementing TypeScript hooks with HookManager, Logger, transforms, context tracking, or troubleshooting SDK features.
mattpocock/skills
handoff
Compact the current conversation into a handoff document for another agent to pick up.
mattpocock/skills
git-guardrails-claude-code
Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
mattpocock/skills
obsidian-vault
Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
mattpocock/skills
setup-pre-commit
Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
mattpocock/skills
edit-article
Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
Didn't find tool you were looking for?