claude-code-hooks

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

🌐 Live site & catalog

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

Post-Tool-Use

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

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

Utils

Tools to help you build and debug hooks.

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

⚡ 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:

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

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:

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

📄 License

MIT © karanb192