claude-code-hooks

🪝 Ready-to-use hooks for Claude Code — safety, automation, notifications, and more.

🎬 Quick Demo

A growing collection of tested, documented hooks you can copy, paste, and customize.

📑 Table of Contents

• Hooks
• Quick Start
• Safety Levels
• Testing
• Contributing

🪝 Hooks

Pre-Tool-Use

Runs before Claude executes a tool. Can block or modify the operation.

| Hook | Matcher | Description | |------|---------|-------------| | block-dangerous-commands | Bash | Blocks dangerous shell commands (rm -rf ~, fork bombs, curl|sh) | | protect-secrets | Read\|Edit\|Write\|Bash | Prevents reading/modifying/exfiltrating sensitive files |

Post-Tool-Use

Runs after Claude executes a tool. Can react to results.

| Hook | Matcher | Description | |------|---------|-------------| | auto-stage | Edit\|Write | Automatically git stages files after Claude modifies them |

Notification

Fires when Claude needs user attention.

| Hook | Matcher | Description | |------|---------|-------------| | notify-permission | permission_prompt\|idle_prompt | Sends Slack alerts when Claude needs input |

Utils

Tools to help you build and debug hooks.

| Tool | Language | Description | |------|----------|-------------| | event-logger | Python | Logs all hook events to inspect payload structures |

💡 Building a new hook? Use event-logger.py to discover what data Claude Code provides for each event before writing your own hooks.

🚀 Quick Start

1. Copy the hook script:

mkdir -p ~/.claude/hooks
cp hook-scripts/pre-tool-use/block-dangerous-commands.js ~/.claude/hooks/

2. Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/block-dangerous-commands.js"
          }
        ]
      }
    ]
  }
}

3. Restart Claude Code — the hook is now active.

💡 Tip: Use multiple hooks together. Combine block-dangerous-commands + protect-secrets for comprehensive safety.

🛡️ Safety Levels

Security hooks support configurable safety levels:

| Level | What's Blocked | Use Case | |-------|----------------|----------| | critical | Catastrophic only (rm -rf ~, fork bombs, dd to disk) | Maximum flexibility | | high | + Risky (force push main, secrets exposure, git reset --hard) | Recommended | | strict | + Cautionary (any force push, sudo rm, docker prune) | Maximum safety |

To change: Edit the SAFETY_LEVEL constant at the top of each hook.

const SAFETY_LEVEL = 'strict'; // or 'critical', 'high'

🧪 Testing

All hooks include comprehensive tests:

# Run all tests
npm test

# Run specific hook tests
node --test hook-scripts/tests/pre-tool-use/block-dangerous-commands.test.js

Test coverage:

• ✅ Unit tests for core functions
• ✅ Integration tests for stdin/stdout flow
• ✅ Config validation tests

📖 Configuration Reference

See the official Claude Code hooks documentation for:

• All hook events and their lifecycles
• Input/output JSON formats
• Matcher patterns
• Environment variables

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Ideas for new hooks:

| Hook | Event | Description | |------|-------|-------------| | protect-tests | PreToolUse | Block test deletion/disabling | | auto-format | PostToolUse | Run prettier/black/gofmt after edits | | branch-guard | PreToolUse | Block changes on main/master branch | | context-snapshot | PreCompact | Preserve context before compaction | | session-summary | Stop | Generate summary on session end | | ntfy-notify | Notification | Free mobile push via ntfy.sh | | discord-notify | Notification | Discord webhook alerts | | cost-tracker | PostToolUse | Track token usage and estimate costs | | tts-alerts | Notification | Voice notifications via say/espeak | | rules-injector | UserPromptSubmit | Auto-inject CLAUDE.md rules | | rate-limiter | PreToolUse | Limit tool calls per minute | | context-injector | SessionStart | Inject project context on session start |

📄 License

MIT © karanb192