claude-code-hooks
🪝 Ready-to-use hooks for Claude Code — plus a 7-plugin installable marketplace: safety, automation, notifications, and more.
🎬 Quick Demo
A growing collection of tested, documented hooks you can copy, paste, and customize.
🔌 New: these hooks also install as one-command Claude Code plugins. Run
/plugin marketplace add karanb192/claude-code-hooks, then/plugin install <name>@claude-code-hooks— see Install as a plugin for the 7-plugin catalog.
📑 Table of Contents
- Hooks
- Install as a plugin
- Quick Start
- Safety Levels
- Testing
- Configuration Reference
- Contributing
- License
🪝 Hooks
Session Lifecycle
Runs at session boundaries — inject context at SessionStart and capture outcomes at Stop / SessionEnd.
🔌
bounty-board(repo TODO/FIXME/HACK debt priced as aging XP bounties) now ships as an installable plugin — see Install as a plugin.
🔌
nerf-receipts(personal model-quality flight recorder) andstandup-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
Runs when the user submits a prompt, before Claude processes it. Can inject context or block the prompt.
🔌
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.
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 |
| protect-tests | Bash|Edit|MultiEdit|Write |
Stops "fake green": blocks deleting, renaming-away, or skip/xfail-disabling tests |
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) andpr-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.
Notification
Fires when Claude needs user attention.
| Hook | Matcher | Description |
|---|---|---|
| notify-permission | permission_prompt|idle_prompt |
Sends Slack alerts when Claude needs input |
Session
Runs on session lifecycle events — start, end, and tool usage during the session.
| Hook | Matcher | Description |
|---|---|---|
| session-logger | SessionStart + PostToolUse + SessionEnd |
Writes a durable markdown log of every session (cwd, git repo, files touched, bash commands). PostToolUse registers with "async": true so logging never blocks Claude; concurrent writes are serialized with a file lock. Bash commands get best-effort secret redaction. Drop-in for Obsidian vaults via CC_SESSION_LOG_DIR. |
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.pyto 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:provenance 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 PostToolUse recorders in these plugins run async — they record in the background and add ~zero latency to a tool call. Each plugin renders on demand via its own command (e.g.
/context-hogs:leaderboard) and at SessionEnd.
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": [