claude-code-hooks
🪝 Ready-to-use hooks for Claude Code, shipped as a 20-plugin installable marketplace: safety, automation, notifications, and more.
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
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.
| Hook | Events | 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. |
| standup-autopilot | SessionStart (startup) + Stop + SessionEnd |
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 |
| nerf-receipts | SessionStart + PostToolUse + PostToolUseFailure + Stop + SubagentStop + SessionEnd |
Personal flight recorder: records your own failure rate, edit churn & tokens/task by model version, and flags real shifts when a model changes |
| bounty-board | SessionStart + PostToolUse + SessionEnd |
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 |
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.
| Hook | Matcher | Description |
|---|---|---|
| instructions-audit | all load reasons (narrow with session_start|nested_traversal|path_glob_match|include|compact) |
Locks the session when a loaded instruction file carries hidden directives: invisible-Unicode smuggling (zero-width, tag characters, variation-selector runs; the TrapDoor supply-chain signature), bidi overrides, directives to read or exfiltrate secrets, curl|sh, decode-and-execute, and hook/settings tampering. Names the rule and line number so you can inspect the file; one install wires the detection arm plus both enforcement arms; HOOK_AUDIT_LEVEL tunes critical/high/strict, HOOK_AUDIT_WARN_ONLY=true warns without locking. |
User-Prompt-Submit
Runs when the user submits a prompt, before Claude processes it. Can inject context or block the prompt.
| Hook | Events | Description |
|---|---|---|
| dead-end-registry | UserPromptSubmit + PreToolUse (Edit|Write) + Stop + SubagentStop + PreCompact |
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 |
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, force push to main) before they run |
| 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 |
| case-insensitive-guard | Bash |
Stops rm -rf content destroying Content on case-insensitive filesystems (APFS/exFAT/NTFS): resolves real targets through cd chains and quotes |
| config-guard | Bash|Edit|MultiEdit|Write |
Who guards the guards: blocks the agent from tampering with its own guardrail config (settings.json, .claude/hooks/, hooks.json, .mcp.json, plugin manifests). Reads always pass. See Config-Change for why and for its out-of-band sibling. |
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 | Read|Grep|Glob|Bash (async) + SessionEnd |
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 |
| pr-provenance-stamp | Edit|MultiEdit|Write|Bash (async) + PreToolUse on Bash |
Stamps a provenance receipt (prompts, est. spend, tests run, agent-authored lines) into your PR body when Claude runs gh pr create |
| dead-rules-audit | Edit|MultiEdit|Write (async) + SessionStart + SessionEnd |
CLAUDE.md compliance scorecard: tallies which rules Claude follows vs ignores as you edit, and flags chronically-ignored rules to promote into a deterministic hook |
Notification
Fires when Claude needs user attention.
| Hook | Matcher | Description |
|---|---|---|
| [notify-permission](plugins/notify-permissio |