claude-code-hooks

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

🎬 Quick Demo

Protecting Secrets	Blocking Dangerous Commands

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

---

📑 Table of Contents

• Hooks
• Install as a plugin
• 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
git-safety	Bash	Branch-aware git guardrails + destructive gh CLI protection

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
format-code	Write|Edit	Auto-formats Python (ruff) and JS/TS/HTML/JSON/MD/YAML (prettier) after edits

🔌 context-hogs (per-file context-cost leaderboard) and pr-provenance-stamp (PR-body provenance receipt) now ship as installable plugins — see Install as a plugin.

🔌 dead-rules-audit (CLAUDE.md compliance scorecard) now ships as an installable plugin — see Install as a plugin.

Session-Start

Runs when a session starts. Can inject context for the session.

🔌 bounty-board (repo TODO/FIXME/HACK debt priced as aging XP bounties) now ships as an installable plugin — see Install as a plugin.

Notification

Fires when Claude needs user attention.

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

Session Lifecycle

Fires on session boundaries — capture outcomes and inject context across sessions.

🔌 nerf-receipts (personal model-quality flight recorder) and standup-autopilot (writes your daily standup from what your agents actually did; re-injects open blockers) now ship as installable plugins — see Install as a plugin.

User-Prompt-Submit

🔌 dead-end-registry (remembers approaches you tried and reverted, then warns before you retry them) now ships as an installable plugin — see Install as a plugin.

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.

---

🔌 Install as a plugin

This repo is also a Claude Code plugin marketplace, so you can install a single hook — no copying scripts, no editing settings.json by hand.

1. Add the marketplace (once):

/plugin marketplace add karanb192/claude-code-hooks

2. Install just the hook you want:

/plugin install context-hogs@claude-code-hooks

3. Restart Claude Code — the hook is active.

Plugin	What it does	Command
context-hogs	Per-file context-cost leaderboard — attributes each tool result's tokens to the files it loaded, so you see which files cost you the most	/context-hogs:leaderboard renders the board on demand
nerf-receipts	Personal flight recorder — records your own failure rate, edit churn & tokens/task by model version, and flags real shifts when a model changes	/nerf-receipts:receipts renders the trend card on demand
dead-rules-audit	CLAUDE.md compliance scorecard — tallies which rules Claude follows vs ignores as you edit (SessionStart + PostToolUse + SessionEnd), and flags chronically-ignored rules to promote into a deterministic hook	/dead-rules-audit:scorecard renders the scorecard on demand
pr-provenance-stamp	Stamps a provenance receipt (prompts, est. spend, tests run, agent-authored lines) into your PR body when Claude runs gh pr create	/pr-provenance-stamp:receipt renders the receipt on demand
standup-autopilot	Writes your daily standup from what your agents actually did across repos — captures tasks, tests, PRs, and blockers from session transcripts and re-injects yesterday's open blockers next session	/standup-autopilot:standup renders today's card on demand
dead-end-registry	Remembers approaches you tried and reverted (reason + estimated token cost) and warns before you retry them — a prompt-submit card plus an ask-before-edit guard	/dead-end-registry:dead-ends renders the registry on demand
bounty-board	Prices your repo's TODO/FIXME/HACK/skip debt as aging XP bounties, injects the top 3 as opportunistic side quests, and verifies + pays out bounties you genuinely clear	/bounty-board:board renders the board on demand

⚡ The context-hogs PostToolUse hook is async — it records in the background and adds zero latency to a tool call. The SessionEnd summary and the /context-hogs:leaderboard command render the leaderboard.

The hooks listed above under 🪝 Hooks install the classic way (copy the script + add to settings.json); more are being packaged as plugins.

---

🚀 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
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