claude-code-hooks

🪝 Production-ready hooks for Claude Code — safety, automation, notifications, and more.

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