claude-code-hooks

July 19, 2026 · View on GitHub

🪝 Ready-to-use hooks for Claude Code — plus a 7-plugin installable marketplace: safety, automation, notifications, and more.

🌐 Live site & catalog

🎬 Quick Demo

Protecting Secrets	Blocking Dangerous Commands

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.

🪝 Hooks

Session Lifecycle

Runs at session boundaries — inject context at SessionStart and capture outcomes at Stop / SessionEnd.

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`.

🔌 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) 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

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) 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.

Notification

Fires when Claude needs user attention.

Hook	Matcher	Description
notify-permission	`permission_prompt\|idle_prompt\|elicitation_dialog`	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.

🔌 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": [
      {
        "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'

🙋 Ask mode (prompt instead of block)

block-dangerous-commands and protect-secrets can ask instead of denying outright. When ask mode is on for a level, matching operations return permissionDecision: "ask" — Claude Code shows the reason and lets you approve or reject, instead of hard-blocking.

Enable per level via environment variables (the literal string true; anything else means deny):

Variable	Affects
`HOOK_ASK_CRITICAL`	`critical`-level patterns (rm -rf ~, .env, …)
`HOOK_ASK_HIGH`	`high`-level patterns (git reset --hard, …)
`HOOK_ASK_STRICT`	`strict`-level patterns (any force push, …)

Set them inline in your hook command in settings.json:

{
  "type": "command",
  "command": "HOOK_ASK_STRICT=true node ~/.claude/hooks/block-dangerous-commands.js"
}

Everything defaults to deny — ask mode is strictly opt-in. A common setup: keep critical on deny, set HOOK_ASK_STRICT=true so cautionary patterns prompt instead of blocking.

🧪 Testing

Requires Node ≥ 18 (no npm dependencies). The format-code tests exercise the real formatters, so have prettier, ruff, and uv on your PATH — CI installs them — or expect those few tests to fail. All hooks include comprehensive tests, run in CI on Node 18, 20, and 22:

# 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
`context-snapshot`	PreCompact	Preserve context before compaction
`ntfy-notify`	Notification	Free mobile push via ntfy.sh
`discord-notify`	Notification	Discord webhook alerts
`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

👤 Author

Built by Karan Bansal, Head of AI at ArmorCode. These hooks are the basis of my OWASP GenAI Summit talk, Hardening AI Coding Agents with Hooks (slides and recording there).

I write about Claude Code, MCP, and production agentic AI at karanbansal.in/blog.