claude-code-hooks

🪝 Ready-to-use hooks for Claude Code, shipped as a 20-plugin installable marketplace: safety, automation, notifications, and more.

🌐 Live site & catalog

Claude Code and agents like it run shell commands, edit files, and install packages on their own. claude-code-hooks enforces least privilege on that autonomy at runtime: every tool call passes through a PreToolUse or PostToolUse hook that allows, denies, or modifies it, with the reason fed back to the agent. Hooks run outside the model as separate processes, so prompt injection can't talk its way past them. The safety set blocks .env and secret exfiltration, curl | sh, rm -rf, force pushes to main, and tampering with the hook config itself; the rest of the catalog handles automation and notifications. Every hook is mapped against the OWASP LLM Top 10 2026.

🎬 Quick Demo

Protecting Secrets	Blocking Dangerous Commands

A growing collection of tested, documented hooks. Every one installs as a one-command Claude Code plugin: run /plugin marketplace add karanb192/claude-code-hooks, then /plugin install <name>@claude-code-hooks; see Install as a plugin for the 20-plugin catalog. Prefer to own the file? Every plugin's script also works standalone: copy plugins/<name>/<name>.js and wire it into settings.json yourself (Quick Start).

📑 Table of Contents

• Hooks
• Install as a plugin
• Quick Start
• Safety Levels
• Testing
• Configuration Reference
• Contributing
• License

🪝 Hooks

Every hook below is an installable plugin; each link goes to the plugin's directory, which holds the script, its tests, and a README. They're grouped by the event that fires them, because the event model is the thing worth learning.

Session Lifecycle

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

Instructions-Loaded

Fires when a CLAUDE.md or .claude/rules/*.md file is loaded into context. The event has no decision control, its exit code is ignored, and current Claude Code builds ignore even the universal continue: false on it (verified live), so detection and enforcement are split: the InstructionsLoaded registration records a per-session lock on a finding (and still emits continue: false for builds that honor it), and the same script registered on UserPromptSubmit and PreToolUse blocks every prompt and tool call for that session until a human fixes the file or deletes the named lock file. The plugin wires all three arms in one install.

User-Prompt-Submit

Runs when the user submits a prompt, before Claude processes it. Can inject context or block the prompt.

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.

Notification

Fires when Claude needs user attention.

Config-Change

Fires when a configuration file changes during a session. Can block the change (exit 2), except for policy_settings.

Why config-guard + config-watch exist: the Aug 2026 CHAINDROP npm worm hid its payload in .claude/settings.json, turning the agent's own config into its persistence mechanism. And CVE-2026-25725 let sandboxed code escape by injecting hooks into a settings.json that did not exist yet, which is why config-guard treats creating a protected file as mutation. config-guard (PreToolUse) blocks the agent itself from rewriting its guardrails before damage happens; config-watch (ConfigChange) covers changes made by anything else while a session runs. For intentional config edits, set CONFIG_GUARD_ALLOW=true for that call, or use ask mode to get a prompt instead of a hard wall.

Install them as a pair:

/plugin install config-guard@claude-code-hooks
/plugin install config-watch@claude-code-hooks

⚠️ Heads-up: once config-guard is active it also blocks claude plugin install/uninstall/disable at its default high level (the plugin manager rewrites config too, including config-guard's own manifest). Install your other plugins first, or set CONFIG_GUARD_ALLOW=true for that one call.

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 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 pure recorder events in these plugins run async: they record in the background and add ~zero latency to a tool call. Guard hooks stay synchronous on purpose: a deny has to land before the tool runs. Plugins with a card render it on demand via their own command (e.g. /context-hogs:leaderboard) and at SessionEnd.

Prefer the classic route? Every plugin's script is self-contained: copy plugins/<name>/<name>.js and register it in settings.json yourself; see Quick Start.

Migrating from hook-scripts/

Earlier versions shipped the standalone scripts under hook-scripts/; that directory is gone and every script now lives in its plugin dir as plugins/<name>/<name>.js. Two situations need action:

• Your settings.json points into a clone of this repo (for example node ~/repos/claude-code-hooks/hook-scripts/pre-tool-use/block-dangerous-commands.js). After you pull, that path no longer exists, and Claude Code treats a failing hook command as a non-blocking error: the guard stops enforcing without any visible sign. Fix it now, not later: install the plugin, or repoint the command at plugins/<name>/<name>.js.
• You copied a script to a stable location (like ~/.claude/hooks/). Your copy keeps working untouched. If you install the plugin version, remove the manual settings.json registration first, or the hook runs twice on every matching event: double latency, double log entries, double denials.

🚀 Quick Start

1. Add the marketplace and install a hook:

/plugin marketplace add karanb192/claude-code-hooks
/plugin install block-dangerous-commands@claude-code-hooks

2. Restart Claude Code: the hook is now active.

The classic way (copy the script)

Every plugin's script works standalone, so you can skip the marketplace and own the file:

1. Copy the hook script:

mkdir -p ~/.claude/hooks
cp plugins/block-dangerous-commands/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: set the HOOK_SAFETY_LEVEL environment variable to critical, high, or strict (anything else falls back to high). All six guard plugins read it: block-dangerous-commands, protect-secrets, git-safety, protect-tests, case-insensitive-guard, and config-guard. (instructions-audit uses HOOK_AUDIT_LEVEL for the same three levels.) The env block in settings.json applies it to every session:

{
  "env": {
    "HOOK_SAFETY_LEVEL": "strict"
  }
}

Running a copied script the classic way? You can still edit the SAFETY_LEVEL default at the top of the hook instead; for installed plugins prefer the env var, since plugin updates overwrite edited files.

const SAFETY_LEVEL = "strict"; // or 'critical', 'high'

🙋 Ask mode (prompt instead of block)

block-dangerous-commands, protect-secrets, case-insensitive-guard, and config-guard 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 in the env block of settings.json (works for plugins and classic copies alike):

{
  "env": {
    "HOOK_ASK_STRICT": "true"
  }
}

Classic copies can also take them inline in the hook 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.

🗺️ OWASP mapping

docs/owasp-llm-top-10-2026.md maps every hook in this repo against the OWASP LLM Top 10 2026, risk by risk. The verdicts are honest: risks a runtime hook genuinely covers are marked covered, risks it cannot touch are marked N/A, and the gaps (rate limiting, output scanning, dependency validation) are listed as wanted contributions. It also points agent-specific risks at the OWASP Top 10 for Agentic Applications and names the four ASI risks these hooks land on.

🧪 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 a single plugin's tests
node --test plugins/block-dangerous-commands/tests/block-dangerous-commands.test.js

Test coverage:

• ✅ Unit tests for core functions
• ✅ Integration tests for stdin/stdout flow
• ✅ Config validation tests

⚡ Performance

A synchronous hook adds its full runtime to every matching tool call. Measured with a fresh Node process per call and a realistic event on stdin, every guard hook here holds a 34-38 ms median on an Apple M3 Pro (Node v26). The two PostToolUse hooks that spawn real subprocesses cost more: auto-stage 68 ms with two git calls, format-code 114 ms with two ruff runs. The harness and committed numbers for all seven hooks live in bench/; reproduce with node bench/run.mjs.

📖 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