claude-code-guardian

claude-code-guardian

Selective security guardrails for Claude Code's --dangerously-skip-permissions mode. Speed by default, intervention by exception.

Why Guardian?

--dangerously-skip-permissions is all-or-nothing. You either approve every single operation manually, or you approve none of them. Most power users choose none -- because stopping to confirm every file write kills the workflow.

The problem: permissionless mode doesn't distinguish between writing a component file and running rm -rf /. Everything gets the same silent green light.

Guardian gives you back the guardrails that actually matter. It hooks into Claude Code's plugin system to intercept operations before they execute. The 99% of safe operations run silently. The 1% that could ruin your day -- destructive shell commands, secret file access, force pushes -- get caught and require your explicit approval.

You keep the speed. You lose the existential dread.

Table of Contents

• What It Catches
• Installation
• Quick Start
• Configuration
  • Configuration File Location
  • Configuration Reference
  • Glob Pattern Syntax
  • Writing Regex Patterns
• How It Works
  • Architecture
  • Bash Guardian (Multi-Layer Defense)
  • Path Guardian (Read/Edit/Write)
  • Auto-Commit (Stop Hook)
  • Archive-Before-Delete
  • Self-Guarding
  • Circuit Breaker
• Security Model
• User Guide
  • Understanding Default Protection
  • Customizing Command Patterns
  • Customizing Path Restrictions
  • Configuring Auto-Commit
  • Working with Multiple Projects
  • Understanding Block Messages
• Troubleshooting
• Disabling Guardian
• Upgrading
• FAQ
• Testing
• Requirements
• License

What It Catches

Safety checkpoints (automatic):

• Auto-commits pending changes when a Claude Code session ends
• Creates a commit before any destructive operation, so you can always roll back
• Archives untracked files to _archive/ before deletion (100MB/file limit, 500MB total, 50 files max)
• Your work is never more than one git reset away from recovery

Hard blocks (always denied, no override):

• rm -rf /, fork bombs, and other catastrophic shell commands
• Reading .env, .pem, SSH keys, and other secret files
• Writing to protected paths outside your project
• git push --force (without --force-with-lease)
• Remote script execution (curl ... | bash)
• Interpreter-mediated file deletion (Python os.remove, Node unlinkSync, etc.)
• Commands exceeding ~100KB / 100,000 bytes (padding attack prevention)

Confirmation prompts (asks before proceeding):

• rm -rf <directory> (non-root recursive deletion)
• git reset --hard, git clean, git stash drop, branch deletion
• git push --force-with-lease
• SQL destructive operations (DROP TABLE, TRUNCATE, DELETE without WHERE)
• Moving protected files (.env, .git, .claude, CLAUDE.md)
• find -exec rm, xargs rm

Protected files (three-tier access control):

Protection Level	Effect	Example Files
Zero Access	Cannot be read, written, or deleted	.env, *.pem, *.key, ~/.ssh/**, ~/.aws/**, *credentials*.json, *.tfstate
Read Only	Can be read, cannot be written or edited	package-lock.json, yarn.lock, node_modules/**, dist/**, __pycache__/**
No Delete	Can be read and edited, cannot be deleted	.gitignore, CLAUDE.md, LICENSE, README.md, Dockerfile, package.json, .github/**

Default patterns cover both Unix and Windows commands.

Installation

Manual Installation (recommended)

Requires Python 3.10+ and Git. Verify with python3 --version and git --version before installing.

git clone https://github.com/idnotbe/claude-code-guardian
claude --plugin-dir /path/to/claude-code-guardian --dangerously-skip-permissions

Note: Point --plugin-dir to the repository root (the directory containing hooks/), not to any subdirectory.

Persistence: The --plugin-dir flag applies to a single session. To load Guardian automatically, add to your shell profile:

# ~/.bashrc or ~/.zshrc
alias claude='claude --plugin-dir /path/to/claude-code-guardian'

To update, run git pull in the cloned directory.