claude-code-hooks
npx machina-cli add skill aiskillstore/marketplace/claude-code-hooks --openclawFiles (1)
SKILL.md
2.9 KB
Claude Code Hooks
Execute custom scripts before/after Claude Code tool invocations.
Quick Reference
| Event | When | Has Matcher |
|---|---|---|
PreToolUse | Before tool execution | Yes |
PostToolUse | After tool completes | Yes |
PermissionRequest | Permission dialog shown | Yes |
Notification | Notifications sent | Yes |
UserPromptSubmit | User submits prompt | No |
Stop | Agent finishes | No |
SubagentStop | Subagent finishes | No |
PreCompact | Before context compaction | No |
SessionStart | Session begins/resumes | No |
SessionEnd | Session ends | No |
Basic Configuration
Add to ~/.claude/settings.json or .claude/settings.local.json:
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/hooks/validate.sh",
"timeout": 5000
}]
}]
}
}
Matcher Patterns
| Pattern | Matches |
|---|---|
"Write" | Only Write tool |
"*" or "" | All tools |
"mcp__*" | All MCP tools |
"Bash" | Bash commands |
Hook Script Requirements
#!/bin/bash
# Receives JSON via stdin: { "tool_name": "...", "tool_input": {...} }
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
# Exit codes:
# 0 = Success (continue)
# 2 = Block with error (stderr shown to Claude)
# Other = Non-blocking error
Common Use Cases
| Use Case | Event | Example |
|---|---|---|
| Validate inputs | PreToolUse | Block dangerous commands |
| Audit logging | PostToolUse | Log all tool usage |
| Custom approval | PermissionRequest | Slack notification |
| Session init | SessionStart | Load project context |
Security Checklist
- Quote all variables:
"$VAR"not$VAR - Validate paths (no
..traversal) - Use
$CLAUDE_PROJECT_DIRfor paths - Set reasonable timeouts
- Handle jq parsing errors
Troubleshooting
# Debug hook loading
claude --debug
# List registered hooks
/hooks
# Test script manually
echo '{"tool_name":"Bash"}' | ./hooks/validate.sh
Official Documentation
- https://code.claude.com/docs/en/hooks - Hooks reference
- https://code.claude.com/docs/en/settings - Settings configuration
Additional Resources
./references/hook-events.md- All events with input/output schemas./references/configuration.md- Advanced config patterns./references/security-patterns.md- Production security
See Also: claude-code-debug for troubleshooting, claude-code-headless for CLI automation
Source
git clone https://github.com/aiskillstore/marketplace/blob/main/skills/0xdarkmatter/claude-code-hooks/SKILL.mdView on GitHub Overview
Claude Code Hooks enables executing custom scripts around Claude Code tool invocations to validate inputs, audit usage, and enforce security. It listens to events such as PreToolUse, PostToolUse, PermissionRequest, Notification, and SessionStart, enabling automated customization of tool flows.
How This Skill Works
Configure hooks in Claude settings. Define PreToolUse entries with a matcher and one or more hook scripts. A hook script receives JSON on stdin with tool_name and tool_input and must exit with codes: 0 to continue, 2 to block with an error, other codes are non blocking.
When to Use It
- Validate inputs before tool execution
- Audit tool usage after tool completion
- Trigger custom approvals via PermissionRequest
- Initialize session by loading project context on SessionStart
- Restrict tool behavior by matching specific tools such as Bash via PreToolUse
Quick Start
- Step 1: Add a PreToolUse hook entry to ~/.claude/settings.json
- Step 2: Create a hook script under hooks/validate.sh that reads JSON input and returns exit codes
- Step 3: Run claude --debug and test with a sample input like {"tool_name":"Bash"} piped to hooks/validate.sh
Best Practices
- Quote all variables in scripts to prevent word splitting
- Validate paths and avoid .. traversal
- Set reasonable timeouts for hook scripts
- Use CLAUDE_PROJECT_DIR for file paths
- Gracefully handle jq parsing errors and provide clear messages
Example Use Cases
- Prevent dangerous commands by blocking with a PreToolUse hook for Bash
- Log all tool usage automatically on PostToolUse for auditing
- Send an approval request via PermissionRequest to Slack
- Load project context on SessionStart to initialize sessions
- Test a hook by simulating input and verifying exit codes with a sample script
Frequently Asked Questions
Add this skill to your agents
