Guardrails for Claude Code

Intercept the
agent loop.

stdin→hook→exit 0 · pass / exit 2 · block

Small programs that watch what Claude Code is about to do — and step in. Block a destructive command. Refuse to read a secret. Stage and format an edit. Ping you on Slack. Nine exhaustively tested copy-paste hooks, plus a seven-plugin marketplace you install with one command.

Install a hook View source

16Hooks + plugins

1238Tests pass

~80msPer call

0 · 2Exit codes

~/repo — claude

          # Claude proposes an action…
          please clean up this directory
          tool    Bash
          command rm -rf ~
          PreToolUseblock-dangerous-commands
          ⊘ blockedexit 2
          "rm -rf on home directory"
          
        

The contract

No SDK. Just a wire protocol.

plain executables
any language
the exit code decides

01 — in

Claude sends `stdin`

On every lifecycle event, Claude Code pipes a JSON payload — the tool, its input, the session — to your hook's standard input.

02 — decide

Your hook runs

A few hundred lines in Node, Python, or shell. Inspect the payload, check it against your rules, and choose a verdict.

03 — out

Return `exit 0` or `exit 2`

0 lets the tool run. 2 blocks it and hands your message back to Claude as guidance.

Where they attach

Eight stops in the loop.

● covered here
○ tool execution

SessionStart

prepare context

UserPrompt

inspect / inject

PreToolUse

block or pass

— tool —

execution

PostToolUse

react / log

Notification

alert you

Stop

finalize

SessionEnd

capture outcome

● covered by this repo — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SessionEnd ○ the middle stop is tool execution — SubagentStop and PreCompact are also covered by the plugins

The catalog

The copy-paste nine.

Want one-command installs instead? Seven plugins ↓

node + python
MIT licensed

PreToolUseBashNode · ~80ms

01block-dangerous-commands

Refuses rm -rf ~, fork bombs, curl | sh, dd to a raw disk, and the long tail of catastrophes that look harmless in a one-liner. Three tunable safety levels decide where the line sits.

block-dangerous-commands

          tool    Bash
          command rm -rf ~
          ⊘ blockedexit 2
          "deletes home directory"
        

PreToolUseRead·Edit·Write·BashNode · ~80ms

02protect-secrets

Stops Claude from reading, editing, or quietly exfiltrating .env files, SSH keys, AWS credentials, kubeconfig — anything load-bearing. Catches the obvious paths and the clever ones: a cat piped to curl is still exfiltration.

protect-secrets

          tool Read
          path .env.production
          ⊘ blockedexit 2
          "sensitive credential file"
        

PreToolUseBashNode · ~80ms

03git-safety

Branch-aware guardrails: blocks commit, merge, rebase, reset and push while you're on main, plus destructive gh CLI calls like gh repo delete. Complements block-dangerous-commands rather than overlapping it.

git-safety

          branch  main
          command git push --force origin main
          ⊘ blockedexit 2
          "force-push to a protected branch"
        

PostToolUseEdit·WriteNode · ~60ms

04auto-stage

After Claude edits or creates a file, runs git add on it — so git diff --cached becomes the canonical "what did the agent just do" view. One less accounting step in your loop.

auto-stage

          # after Edit succeeds
          git add src/api.ts
          ✓ stagedexit 0
          review → git diff --cached
        

PostToolUseWrite·EditNode

05format-code

Runs the right formatter on whatever Claude just wrote — ruff for Python, prettier for JS/TS/HTML/JSON/Markdown/YAML. The agent's output lands already clean, so diffs stay about logic, not whitespace.

format-code

          # after Write app.py
          ruff format app.py
          ✓ formattedexit 0
          1 file reformatted
        

Notificationpermission · idleNode · ~80ms

06notify-permission

Pings a Slack channel when Claude is stuck on a permission prompt or has gone idle waiting on you. Start a long agentic run, switch tabs, and trust you'll be pulled back when it actually needs a human.

notify-permission

          event permission_prompt
          tool  Bash (sudo)
          ↗ slack#claude-runs
          "Claude needs you in repo X"
        

PreToolUseBash · Edit · WriteNode · ~80ms

07protect-tests

Stops the "fake green" ending: an agent that can't make a test pass will sometimes delete it, rename it out of discovery, or slip in a .skip. This hook refuses all three — while still allowing you to re-enable tests freely.

protect-tests

          tool Edit
          file auth.test.js → describe.skip(
          ⊘ blockedexit 2
          "tests must fail honestly"
        

SessionStart · SessionEndPostToolUse · asyncNode · ~80ms

08session-logger

Writes a durable markdown log of every session — repo, files touched, bash commands (secrets redacted) — without adding a millisecond to the loop. Point CC_SESSION_LOG_DIR at an Obsidian vault and your agent keeps a diary.

session-logger

          event SessionEnd
          repo  ~/repo · 14 files · 31 cmds
          ✎ loggedsessions/2026-07-19.md
          "every session, remembered"
        

PreToolUseBashNode · ~80ms

09case-insensitive-guard

On APFS, exFAT and NTFS, Content and content are the same path — an agent typing the wrong case deletes the real thing. Resolves every rm/mv target through cd chains and quotes, and blocks only provable case-collisions.

case-insensitive-guard

          tool    Bash
          command cd app && rm -rf Content
          ⊘ blockedexit 2
          "'content' exists — same path on this disk"
        

+ event-logger — a Python diagnostic that dumps every event's JSON so you can see an event's shape before you write a hook against it. The thing you reach for first.

The marketplace

Seven plugins. One command each.

node · MIT
/plugin install

~/repo — claude

        # 1 · add the marketplace, once
        /plugin marketplace add karanb192/claude-code-hooks
        # 2 · install any of the seven by name
        /plugin install context-hogs@claude-code-hooks
        ✓ ready7 plugins available
        # or from your shell — claude plugin marketplace add · claude plugin install
      

10context-hogs

Per-file context-cost leaderboard — which files eat your tokens.

/context-hogs:leaderboard

PostToolUseSessionEnd

11nerf-receipts

Personal model-quality flight recorder — your own receipts when Claude feels nerfed.

/nerf-receipts:receipts

SessionStartPostToolUsePostToolUseFailureStopSubagentStopSessionEnd

12dead-rules-audit

CLAUDE.md compliance scorecard — which rules Claude actually ignores.

/dead-rules-audit:scorecard

SessionStartPostToolUseSessionEnd

13pr-provenance-stamp

Stamps a prompts / spend / tests / agent-authored receipt into PR bodies on gh pr create.

/pr-provenance-stamp:provenance

PreToolUsePostToolUse

14standup-autopilot

Writes your standup from what your agents actually did; re-injects yesterday's blockers.

/standup-autopilot:standup

SessionStartStopSessionEnd

15dead-end-registry

Remembers tried-and-reverted approaches; warns before you pay for a dead end twice.

/dead-end-registry:dead-ends

UserPromptSubmitPreToolUseStopSubagentStopPreCompact

16bounty-board

Prices TODO/FIXME debt as aging XP bounties; agents clear them as side quests.

/bounty-board:board

SessionStartPostToolUseSessionEnd

Most recorders observe off the critical path — their PostToolUse and Stop hooks run async: true, so they write their receipts without adding latency to the agent loop. The exception is a hook whose output Claude reads back: bounty-board verifies and pays out its bounties synchronously.

The classic path

Copy. Register. Restart.

This is the copy-paste nine. The seven plugins install with /plugin ↑ instead.

~60 seconds
no build step

STEP i

Place the script

Anywhere your shell can chmod +x. Convention is ~/.claude/hooks/.

$ mkdir -p ~/.claude/hooks
$ cp hook-scripts/pre-tool-use/block-dangerous-commands.js \
     ~/.claude/hooks/

STEP ii

Register it

In .claude/settings.json, bind the hook to an event and matcher.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "node ~/.claude/hooks/block-dangerous-commands.js"
      }]
    }]
  }
}

STEP iii

Restart Claude Code

The hook is live. Ask Claude to do something reckless and watch it refuse.

$ claude
› please rm -rf ~
… hook blocked:
  deletes home directory.

Marginalia

Tradeoffs, in brief.

Safety

Three levels of paranoia

criticalcatastrophes only — rm -rf ~, fork bombs, dd

high+ risky — force push, secrets, hard reset★ default

strict+ cautionary — any force push, sudo rm

Runtime

Match language to event rate

Bashtiny guards10–20ms

Nodeper-tool, JSON-heavy50–100ms

Pythonsession events200–400ms

Exits

Two numbers do the work

0pass — let the tool run

2block — message goes back to Claude

·other — non-blocking warning, logged

Open

Forthcoming hooks.

contributions welcome
see CONTRIBUTING.md

17context-snapshot — preserve before compactionPreCompact

18ntfy-notify — free mobile pushNotification

19discord-notify — webhook alertsNotification

20tts-alerts — voice notifications via say/espeakNotification

21rules-injector — auto-attach CLAUDE.mdUserPromptSubmit

22rate-limiter — cap tool calls per minutePreToolUse

Put a hook in the loop.

Sixteen tested tools — nine copy-paste guardrails plus seven one-command plugins, MIT licensed, no framework to learn. Install one and restart Claude Code — you're protected in under a minute.

Star on GitHub Read the essay

Intercept theagent loop.

No SDK. Just a wire protocol.

Claude sends stdin

Your hook runs

Return exit 0 or exit 2

Eight stops in the loop.

The copy-paste nine.

01block-dangerous-commands

02protect-secrets

03git-safety

04auto-stage

05format-code

06notify-permission

07protect-tests

08session-logger

09case-insensitive-guard

Seven plugins. One command each.

10context-hogs

11nerf-receipts

12dead-rules-audit

13pr-provenance-stamp

14standup-autopilot

15dead-end-registry

16bounty-board

Copy. Register. Restart.

Place the script

Register it

Restart Claude Code

Tradeoffs, in brief.

Three levels of paranoia

Match language to event rate

Two numbers do the work

Forthcoming hooks.

Put a hook in the loop.

Intercept the
agent loop.

Claude sends `stdin`

Return `exit 0` or `exit 2`