Claude Code Guardrails

Safety hooks for Claude Code. Designed to refuse destructive shell commands, credential writes, and unreviewed external MCP calls — in any project, on macOS, Linux, or Windows.

Copy one file into your project and these checks run on every Claude Code tool call in it.

[!IMPORTANT] This is one layer of defence, not a solution, and it is not foolproof. It is pattern matching over the text of a tool call — useful against an agent making a mistake, and no substitute for backups, server-side branch protection, or reviewing what an agent does. It will not catch everything and is not intended to. If it cannot load, it fails open and your session runs unprotected — so the absence of a block never means a command was checked and approved.

Provided "as is", with no warranty and no liability, under the MIT License. Read DISCLAIMER.md before relying on it for anything you cannot afford to lose.

Don't trust it — check it. This tool asks for a hook on every tool call in your project, so it should have to earn that. bash run-vuln-tests.sh runs 149 offline evasion attempts against the guards and tells you which ones got through. SECURITY.md states plainly what the guards do not defend against.

What it is designed to refuse

The patterns below are what the checks look for. The list is not exhaustive of destructive commands — it is exhaustive of what these checks recognise. Any spelling not listed, and anything the shell only assembles at run time, passes through.

A blocking check exits 2 and returns a reason, so Claude sees why it was stopped and can correct course. Guardrails restrain the agent, not you — every blocked command can still be run manually.

"Any write tool" is literal: the dispatcher routes Write, Edit, MultiEdit, NotebookEdit and anything else matching *Edit/*Write, so a newly introduced file-mutating tool is guarded by default rather than silently unguarded until someone adds its name.

Git-level guard: pushes to main

The checks above restrain Claude. This one restrains the git client itself — it catches a push to a protected branch whichever caller runs it, unless that caller skips hooks (see the caveat below).

bash git-hooks/install.sh          # current repo
bash git-hooks/install.sh ../app   # another repo
powershell git-hooks/install.ps1   # Windows

It inspects the <remote-ref> git reports for each pushed ref, which git resolves after refspecs, HEAD and upstream tracking are expanded — so one check covers git push origin main, git push origin HEAD:main, git push --delete origin main, and a bare git push from a branch whose upstream is main. Tags and non-protected branches pass through untouched.

An existing pre-push hook is renamed to pre-push.local and still runs, after the guard. If the repo sets core.hooksPath, the installer follows it there — otherwise the hook would be a silent no-op.

This is a local safety net, not access control: git push --no-verify bypasses it and other clones do not have it. Pair it with a server-side branch protection rule requiring a pull request.

Install

1. Copy the bootstrap script

Copy run-hooks.sh into your project at .claude/hooks/run-hooks.sh and commit it. On Windows, copy run-hooks.ps1 alongside it.

That is the only file your project needs to vendor. The rest of the library is resolved (and cached) automatically on first use — see Resolution order.

2. Wire it into .claude/settings.json

macOS / Linux

{
  "hooks": {
    "PreToolUse": [{ "type": "command", "command": "bash .claude/hooks/run-hooks.sh pre" }],
    "PostToolUse": [{ "type": "command", "command": "bash .claude/hooks/run-hooks.sh post" }]
  }
}

Windows

{
  "hooks": {
    "PreToolUse": [{ "type": "command", "command": "powershell .claude/hooks/run-hooks.ps1 pre" }],
    "PostToolUse": [{ "type": "command", "command": "powershell .claude/hooks/run-hooks.ps1 post" }]
  }
}

3. Verify

Start a Claude Code session and ask it to run rm -rf /tmp/example. It should be blocked with a [guardrail] reason.

Requirements

• bash in PATH. All check logic lives in .sh files — a single source of truth across platforms. On Windows, install Git for Windows (includes Git Bash) or enable WSL. run-hooks.ps1 is a thin launcher that delegates to bash.
• Node.js in PATH, used to parse the hook JSON payload.

Resolution order

run-hooks.sh looks for the hook library in four places, in order:

1. $CLAUDE_GUARDRAILS_HOME — an explicit local checkout
2. A sibling checkout: <project>/../guardrails or <project>/../claude-guardrails
3. The per-user cache (~/.claude/guardrails), refreshed once per TTL window
4. Auto-clone from $CLAUDE_GUARDRAILS_REPO into that cache

If all four fail it exits 0 (fails open) so Claude Code is never blocked by a broken guardrail install — it prints a warning instead.

Configuration

Per-project opt-out

Create .claude/hooks-skip.json in your project root and name the checks to skip:

{ "skip": ["check-production-guard", "check-no-hardcoded-paths"] }

MCP classification registry

check-mcp-guardrail.sh and the auto-classifier (mcp-classify.js) both read .claude/hooks/mcp-registry.json inside your project. This file is not created automatically — create it once per project by copying the starter:

mkdir -p .claude/hooks
cp examples/mcp-registry.json .claude/hooks/mcp-registry.json

Without it, post-tool-use.sh skips auto-classification entirely and every mcp__* tool is treated as external, so every MCP call raises the consent banner — including purely local ones.