claude-code-hooks

claude-code-hooks

🪝 Ready-to-use hooks for Claude Code, shipped as a 22-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

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 22-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
• Token Diet
• 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.
subagent-spawn-cap	Agent|Task	Per-session subagent spawn budget: asks at spawn 20 and every 10 after, denies at 60, nested fan-outs included. The total cap Claude Code 2.1.224 removed, back under your control.

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	permission_prompt|idle_prompt|elicitation_dialog	Sends Slack alerts when Claude needs input

Config-Change

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

Hook	Matcher	Description
config-watch	user_settings|project_settings|local_settings|policy_settings|skills	Makes every mid-session config change loudly visible (default), or blocks it outright with CONFIG_WATCH_BLOCK=true. Note: the docs guarantee ConfigChange can block via exit 2 but do not document its payload schema, so the hook parses defensively and logs the raw payload.