One command to make Claude Code safe for autonomous operation. 637 example hooks · 13,931 tests · 1,000+ installs/day · 日本語
npx cc-safe-setupInstalls 8 safety hooks in ~10 seconds. Blocks rm -rf /, prevents pushes to main, catches secret leaks, validates syntax after every edit. Zero dependencies.
What's a hook? A checkpoint that runs before Claude executes a command. Like airport security — it inspects what's about to happen and blocks anything dangerous before it reaches the gate.
Getting Started · All Tools · Recipes · Validate your settings.json · Check your score (npx cc-health-check)
cc-safe-setup
Make Claude Code safe for autonomous operation
Prevents real incidents (from GitHub Issues):
✗ rm -rf deleted entire user directory via NTFS junction (#36339)
✗ Remove-Item -Recurse -Force destroyed unpushed source (#37331)
✗ Entire Mac filesystem deleted during cleanup (#36233)
✗ Untested code pushed to main at 3am
✗ Force-push rewrote shared branch history
✗ API keys committed to public repos via git add .
✗ Syntax errors cascading through 30+ files
✗ Sessions losing all context with no warning
Hooks to install:
● Destructive Command Blocker
● Branch Push Protector
● Post-Edit Syntax Validator
● Context Window Monitor
● Bash Comment Stripper
● cd+git Auto-Approver
● Secret Leak Prevention
Install all 8 safety hooks? [Y/n] Y
✓ Done. 8 safety hooks installed.
A Claude Code user lost their entire C:\Users directory when rm -rf followed NTFS junctions. Another lost all source code when Claude ran Remove-Item -Recurse -Force * on a repo. Others had untested code pushed to main at 3am. API keys got committed via git add .. Syntax errors cascaded through 30+ files before anyone noticed.
Claude Code ships with no safety hooks by default. This tool fixes that.
Works with Auto Mode. Claude Code's Auto Mode sandboxing provides container-level isolation. cc-safe-setup adds process-level hooks as defense-in-depth — catching destructive commands even outside sandboxed environments.
| Hook | Prevents | Related Issues |
|---|---|---|
| Destructive Guard | rm -rf /, git reset --hard, git clean -fd, git checkout --force, sudo + destructive, PowerShell Remove-Item -Recurse -Force, rd /s /q, NFS mount detection |
#36339 #36640 #37331 |
| Branch Guard | Pushes to main/master + force-push (--force) on all branches |
|
| Secret Guard | git add .env, credential files, git add . with .env present |
#6527 |
| Syntax Check | Python, Shell, JSON, YAML, JS errors after edits | |
| Context Monitor | Session state loss from context window overflow (40%→25%→20%→15% warnings) | |
| Comment Stripper | Bash comments breaking permission allowlists | #29582 |
| cd+git Auto-Approver | Permission prompt spam for cd /path && git log |
#32985 #16561 |
| API Error Alert | Silent session death from rate limits or API errors — desktop notification + log |
Each hook exists because a real incident happened without it.
Hooks now support an if field for conditional execution. The hook process only spawns when the command matches the pattern — ls won't trigger a git-only hook.
{
"type": "command",
"if": "Bash(git push *)",
"command": "~/.claude/hooks/test-before-push.sh"
}All example hooks include if field documentation in their headers.
Override Claude Code's built-in confirmation prompts. These run after the built-in safety checks, so they can auto-approve prompts that permissions.allow cannot suppress.
| Hook | What It Solves | Issue |
|---|---|---|
quoted-flag-approver |
"Quoted characters in flag names" prompt on git commit -m "msg" |
#27957 |
bash-heuristic-approver |
Safety heuristic prompts for $(), backticks, ANSI-C quoting |
#30435 |
edit-always-allow |
Edit prompts in .claude/skills/ despite bypassPermissions |
#36192 |
allow-git-hooks-dir |
Edit prompts in .git/hooks/ for pre-commit/pre-push setup |
|
allow-protected-dirs |
All protected directory prompts (CI/Docker environments) | #36168 |
git-show-flag-sanitizer |
Strips invalid --no-stat from git show (wastes context on error) |
#13071 |
compact-blocker |
Blocks auto-compaction via PreCompact (preserves full context) | #6689 |
webfetch-domain-allow |
Auto-approves WebFetch by domain (fixes broken domain:* wildcard) |
#9329 |
Install any of these: npx cc-safe-setup --install-example <name>
| Command | What It Does |
|---|---|
npx cc-safe-setup |
Install 8 safety hooks |
--create "desc" |
Generate hook from plain English |
--audit [--fix|--json|--badge] |
Safety score 0-100 |
--lint |
Static analysis of config |
--diff <file> |
Compare settings |
--compare <a> <b> |
Side-by-side hook comparison |
--migrate |
Detect hooks from other projects |
--generate-ci |
Create GitHub Actions workflow |
--share |
Generate shareable URL |
--benchmark |
Measure hook speed |
--dashboard |
Real-time terminal UI |
--issues |
GitHub Issues each hook addresses |
--doctor |
Diagnose hook problems |
--watch |
Live blocked command feed |
--stats |
Block history analytics |
--learn [--apply] |
Pattern learning |
--scan [--apply] |
Tech stack detection |
--export / --import |
Team config sharing |
--verify |
Test each hook |
--install-example <name> |
Install from 640+ examples |
--examples [filter] |
Browse examples by keyword |
--full |
All-in-one setup |
--status |
Check installed hooks |
--dry-run |
Preview changes |
--uninstall |
Remove all hooks |
--shield |
Maximum safety in one command |
--guard "rule" |
Instantly enforce a rule from English |
--suggest |
Predict risks from project analysis |
--from-claudemd |
Convert CLAUDE.md rules to hooks |
--team |
Project-level hooks for git sharing |
--profile [level] |
Switch safety profiles |
--save-profile <name> |
Save current hooks as profile |
--analyze |
Session analysis dashboard |
--health |
Hook health table |
--quickfix |
Auto-fix common problems |
--replay |
Visual blocked commands timeline |
--why <hook> |
Show real incident behind hook |
--migrate-from <tool> |
Migrate from other hook tools |
--diff-hooks [path] |
Compare hook configurations |
--init-project |
Full project setup (hooks + CLAUDE.md + CI) |
--score |
CI-friendly safety score (exit 1 if below threshold) |
--test-hook <name> |
Test a specific hook with sample input |
--simulate "cmd" |
Preview how all hooks react to a command |
--protect <path> |
Block edits to a file or directory |
--rules [file] |
Compile YAML rules into hooks |
--validate |
Validate all hook scripts (syntax + structure) |
--safe-mode |
Maximum protection: all safety hooks + strict config |
--changelog |
Show what changed in each version |
--report |
Generate safety report |
--help |
Show help |
| I want to... | Command |
|---|---|
| Make Claude Code safe right now | npx cc-safe-setup --shield |
| Stop permission prompt spam | npx cc-safe-setup --install-example auto-approve-readonly |
| Enforce a rule instantly | npx cc-safe-setup --guard "never delete production data" |
| See what risks my project has | npx cc-safe-setup --suggest |
| Convert CLAUDE.md rules to hooks | npx cc-safe-setup --from-claudemd |
| Share hooks with my team | npx cc-safe-setup --team && git add .claude/ |
| Choose a safety level | npx cc-safe-setup --profile strict |
| See what Claude blocked today | npx cc-safe-setup --replay |
| Know why a hook exists | npx cc-safe-setup --why destructive-guard |
| Block silent memory file edits | npx cc-safe-setup --install-example memory-write-guard |
| Stop built-in skills editing opaquely | npx cc-safe-setup --install-example skill-gate |
| Diagnose why hooks aren't working | npx cc-safe-setup --doctor |
| Preview how hooks react to a command | npx cc-safe-setup --simulate "git push origin main" |
| Protect a specific file from edits | npx cc-safe-setup --protect .env |
| Stop .git/ write prompts | npx cc-safe-setup --install-example allow-git-hooks-dir |
| Auto-approve compound git commands | npx cc-safe-setup --install-example auto-approve-compound-git |
| Detect prompt injection patterns | npx cc-safe-setup --install-example prompt-injection-detector |
| Define rules in YAML, compile to hooks | npx cc-safe-setup --rules rules.yaml |
| Validate all hook scripts are correct | npx cc-safe-setup --validate |
| Maximum protection mode | npx cc-safe-setup --safe-mode |
| Migrate from Cursor/Windsurf | Migration Guide |
| Problem | Issue | Fix |
|---|---|---|
Claude uses cat/grep/sed instead of built-in Read/Edit/Grep |
#19649 (48👍) | npx cc-safe-setup --install-example prefer-builtin-tools |
cd /path && cmd bypasses permission allowlist |
#28240 (88👍) | npx cc-safe-setup --install-example compound-command-approver |
| Multiline commands skip pattern matching | #11932 (47👍) | Use hooks instead of allowlist patterns for complex commands |
| No notification when Claude asks a question | #13024 (52👍) | npx cc-safe-setup --install-example notify-waiting |
allow overrides ask in permissions |
#6527 (17👍) | Use hooks to block dangerous commands instead of ask rules |
Plans stored in ~/.claude/ with random names |
#12619 (163👍) | npx cc-safe-setup --install-example plan-repo-sync |
- Writes hook scripts to
~/.claude/hooks/ - Updates
~/.claude/settings.jsonto register the hooks - Restart Claude Code — hooks are active
Safe to run multiple times. Existing settings are preserved. A backup is created if settings.json can't be parsed.
Maximum safety: npx cc-safe-setup --shield — one command: fix environment, install hooks, detect stack, configure settings, generate CLAUDE.md.
Instant rule: npx cc-safe-setup --guard "never touch the database" — generates, installs, activates a hook instantly from plain English.
Team setup: npx cc-safe-setup --team — copy hooks to .claude/hooks/ with relative paths, commit to repo for team sharing.
Preview first: npx cc-safe-setup --dry-run
Check status: npx cc-safe-setup --status — see which hooks are installed (exit code 1 if missing).
Verify hooks work: npx cc-safe-setup --verify — sends test inputs to each hook and confirms they block/allow correctly.
Troubleshoot: npx cc-safe-setup --doctor — diagnoses why hooks aren't working (jq, permissions, paths, shebang).
Live monitor: npx cc-safe-setup --watch — real-time dashboard of blocked commands during autonomous sessions.
Uninstall: npx cc-safe-setup --uninstall — removes all hooks and cleans settings.json.
Requires: jq for JSON parsing (brew install jq / apt install jq).
Note: Hooks are skipped when Claude Code runs with --bare or --dangerously-skip-permissions. These modes bypass all safety hooks by design.
Known limitation: In headless mode (-p / --print), hook exit code 2 may not block tool execution (#36071). For CI pipelines, use interactive mode with hooks rather than -p mode.
Run npx cc-health-check to see the difference:
| Before | After | |
|---|---|---|
| Safety Guards | 25% | 75% |
| Overall Score | 50/100 | 95/100 |
| Destructive commands | Unprotected | Blocked |
| Force push | Allowed | Blocked |
.env in git |
Possible | Blocked |
| Context warnings | None | 4-stage alerts |
| Variable | Hook | Default |
|---|---|---|
CC_ALLOW_DESTRUCTIVE=1 |
destructive-guard | 0 (protection on) |
CC_SAFE_DELETE_DIRS |
destructive-guard | node_modules:dist:build:.cache:__pycache__:coverage |
CC_PROTECT_BRANCHES |
branch-guard | main:master |
CC_ALLOW_FORCE_PUSH=1 |
branch-guard | 0 (protection on) |
CC_SECRET_PATTERNS |
secret-guard | .env:.env.local:credentials:*.pem:*.key |
CC_CONTEXT_MISSION_FILE |
context-monitor | $HOME/mission.md |
Verify your setup:
npx cc-health-checkcc-safe-setup gives you 8 essential hooks. Want to know what else your setup needs?
Run npx cc-health-check (free, 20 checks) to see your current score. If it's below 80, the Claude Code Ops Kit fills the gaps — 6 hooks + 5 templates + 9 scripts + install.sh. Pay What You Want ($0+).
Or browse the free hooks: claude-code-hooks
Try it in your browser — paste your settings.json, get a score instantly. Nothing leaves your browser.
Or from the CLI:
npx cc-safe-setup --auditAnalyzes 9 safety dimensions and gives you a score (0-100) with one-command fixes for each risk.
# .github/workflows/safety.yml
- uses: yurukusa/cc-safe-setup@main
with:
threshold: 70 # CI fails if score drops below thisnpx cc-safe-setup --scan # detect tech stack, recommend hooks
npx cc-safe-setup --scan --apply # auto-create CLAUDE.md with project rulesnpx cc-safe-setup --create "block npm publish without tests"
npx cc-safe-setup --create "auto approve test commands"
npx cc-safe-setup --create "block curl pipe to bash"
npx cc-safe-setup --create "block DROP TABLE and TRUNCATE"9 built-in templates + generic fallback. Creates the script, registers it, and runs a smoke test.
npx cc-safe-setup --learn # analyze your block history for patterns
npx cc-safe-setup --learn --apply # auto-generate custom hooks from patternsNeed custom hooks beyond the 8 built-in ones? Install any example with one command:
npx cc-safe-setup --install-example block-database-wipeOr browse all available examples in examples/:
- auto-approve-git-read.sh — Auto-approve
git status,git log, even with-Cflags - auto-approve-ssh.sh — Auto-approve safe SSH commands (
uptime,whoami, etc.) - enforce-tests.sh — Warn when source files change without corresponding test files
- notify-waiting.sh — Desktop notification when Claude Code waits for input (macOS/Linux/WSL2)
- edit-guard.sh — Block Edit/Write to protected files (defense-in-depth for #37210)
- auto-approve-build.sh — Auto-approve npm/yarn/cargo/go/python build, test, and lint commands
- auto-approve-docker.sh — Auto-approve docker build, compose, ps, logs, and other safe commands
- block-database-wipe.sh — Block destructive database commands: Laravel
migrate:fresh, Djangoflush, Railsdb:drop, rawDROP DATABASE(#37405 #37439) - auto-approve-python.sh — Auto-approve pytest, mypy, ruff, black, isort, flake8, pylint commands
- auto-snapshot.sh — Auto-save file snapshots before edits for rollback protection (#37386 #37457)
- allowlist.sh — Block everything not explicitly approved — inverse permission model (#37471)
- protect-dotfiles.sh — Block modifications to
~/.bashrc,~/.aws/,~/.ssh/and chezmoi without diff (#37478) - scope-guard.sh — Block file operations outside project directory — absolute paths, home, parent escapes (#36233)
- auto-checkpoint.sh — Auto-commit after every edit for rollback protection (#34674)
- git-config-guard.sh — Block
git config --globalmodifications without consent (#37201) - deploy-guard.sh — Block deploy commands when uncommitted changes exist (#37314)
- network-guard.sh — Warn on suspicious network commands sending file contents (#37420)
- test-before-push.sh — Block
git pushwhen tests haven't been run (#36970) - large-file-guard.sh — Warn when Write tool creates files over 500KB
- commit-message-check.sh — Warn on non-conventional commit messages (feat:, fix:, docs:, etc.)
- env-var-check.sh — Block hardcoded API keys (sk-, ghp_, glpat-) in export commands
- timeout-guard.sh — Warn before long-running commands (npm start, rails s, docker-compose up)
- branch-name-check.sh — Warn on non-conventional branch names (feature/, fix/, etc.)
- todo-check.sh — Warn when committing files with TODO/FIXME/HACK markers
- path-traversal-guard.sh — Block Edit/Write with
../../path traversal and system directories - case-sensitive-guard.sh — Detect case-insensitive filesystems (exFAT, NTFS, HFS+) and block rm/mkdir that would collide due to case folding (#37875)
- compound-command-approver.sh — Auto-approve safe compound commands (
cd && git log,cd && npm test) that the permission system can't match (#30519 #16561) - tmp-cleanup.sh — Clean up accumulated
/tmp/claude-*-cwdfiles on session end (#8856) - session-checkpoint.sh — Save session state to mission file before context compaction (#37866)
- verify-before-commit.sh — Block git commit when lint/test commands haven't been run (#37818)
- hook-debug-wrapper.sh — Wrap any hook to log input/output/exit code/timing to
~/.claude/hook-debug.log - loop-detector.sh — Detect and break command repetition loops (warn at 3, block at 5 repeats)
- commit-quality-gate.sh — Warn on vague commit messages ("update code"), long subjects, mega-commits
- session-handoff.sh — Auto-save git state and session info to
~/.claude/session-handoff.mdon session end - diff-size-guard.sh — Warn/block when committing too many files at once (default: warn at 10, block at 50)
- dependency-audit.sh — Warn when installing packages not in manifest (npm/pip/cargo supply chain awareness)
- env-source-guard.sh — Block sourcing .env files into shell environment (#401)
- symlink-guard.sh — Detect symlink/junction traversal in rm targets (#36339 #764)
- no-sudo-guard.sh — Block all sudo commands
- no-install-global.sh — Block npm -g and system-wide pip
- no-curl-upload.sh — Warn on curl POST/upload (data exfiltration)
- no-port-bind.sh — Warn on network port binding
- git-tag-guard.sh — Block pushing all tags at once
- npm-publish-guard.sh — Version check before npm publish
- max-file-count-guard.sh — Warn when 20+ new files created per session
- protect-claudemd.sh — Block edits to CLAUDE.md and settings files
- reinject-claudemd.sh — Re-inject CLAUDE.md rules after compaction (#6354)
- binary-file-guard.sh — Warn when Write targets binary file types (images, archives)
- stale-branch-guard.sh — Warn when working branch is far behind default
- cost-tracker.sh — Estimate session token cost and warn at thresholds ($1, $5)
- read-before-edit.sh — Warn when editing files not recently read (prevents old_string mismatches)
SAFETY_CHECKLIST.md — Copy-paste checklist for before/during/after autonomous sessions.
Works on Windows via WSL or Git Bash. Native PowerShell is not supported (hooks are bash scripts).
Common issue: If you see Permission denied or No such file errors after install, run:
npx cc-safe-setup --doctorThis detects Windows backslash paths (C:\Users\... → C:/Users/...) and missing execute permissions.
See Issue #1 for details.
TROUBLESHOOTING.md — "Hook doesn't work" → step-by-step diagnosis. Covers every common failure pattern.
SETTINGS_REFERENCE.md — Complete reference for permissions, hooks, modes, and common configurations. Includes known limitations and workarounds.
MIGRATION.md — Step-by-step guide for moving from permissions-only to permissions + hooks. Keep your existing config, add safety layers on top.
- Hook Design Guide (Zenn Book) — 14-chapter guide from 700+ hours of autonomous operation. Hook design patterns, testing strategies, real incident postmortems. Chapter 2 free
- Cookbook — 26 practical recipes (block, approve, protect, monitor, diagnose)
- Official Hooks Reference — Claude Code hooks documentation
- Hooks Cookbook — 25 recipes from real GitHub Issues (interactive version)
- Skills Guide deep-dive (Qiita, 19K+ views) — Anthropic's official Skills PDF analyzed with 40% token reduction
- Japanese guide (Qiita) — この記事の日本語解説
- v2.1.85
iffield guide (Qiita) — Reduce hook overhead with conditional execution - Hook Test Runner —
npx cc-hook-test <hook.sh>to auto-test any hook - Hook Registry —
npx cc-hook-registry search database(browse online) - Hooks Cheat Sheet — printable A4 quick reference
- Ecosystem Comparison — all Claude Code hook projects compared
- The incident that inspired this tool — NTFS junction rm -rf
- How to prevent rm -rf disasters — real incidents and the hook that stops them
- How to prevent force-push to main — branch protection via hooks
- How to prevent secret leaks — stop git add . from committing .env
Q: I installed hooks but Claude says "Unknown skill: claude-code-hooks:setup"
cc-safe-setup installs hooks, not skills or plugins. Hooks run automatically in the background — you don't invoke them manually. After install + restart, try running a dangerous command; the hook will block it silently.
Q: cc-health-check says to run cc-safe-setup but I already did
cc-safe-setup covers Safety Guards (75-100%) and Monitoring (context-monitor). The other health check dimensions (Code Quality, Recovery, Coordination) require additional CLAUDE.md configuration or manual hook installation from claude-code-hooks.
Q: Will hooks slow down Claude Code?
No. Each hook runs in ~10ms. They only fire on specific events (before tool use, after edits, on stop). No polling, no background processes.
Q: My permission patterns don't match compound commands like cd /path && git status
This is a known limitation of Claude Code's permission system (#16561, #28240). Permission matching evaluates only the first token (cd), not the actual command (git status). Use a PreToolUse hook instead — hooks see the full command string and can parse compound commands. See compound-command-allow.sh in examples.
Q: --dangerously-skip-permissions still prompts for .claude/ and .git/ writes
Since v2.1.78, protected directories always prompt regardless of permission mode (#35668). Use a PermissionRequest hook to auto-approve specific protected directory operations. See allow-protected-dirs.sh in examples.
Q: allow: ["Bash(*)"] overrides my ask rules
allow takes precedence over ask. If you allow all Bash, ask rules are ignored (#6527). Use PreToolUse hooks to block dangerous commands instead of relying on the ask/allow priority system.
Still stuck? See the full Permission Troubleshooting Flowchart for step-by-step diagnosis.
Report a problem: Found a false positive or a bypass? Open an issue. Include the command that was incorrectly blocked/allowed and your OS.
Request a hook: Describe the problem you're trying to prevent (not the solution). We'll figure out the hook together.
Write a hook: Fork, add your .sh file to examples/, add tests to test.sh, and open a PR. Every hook needs:
- A comment header explaining what it blocks and why
- At least 7 test cases (block, allow, empty input, edge cases)
bash -nsyntax validation passing
Share your experience: Used cc-safe-setup and have feedback? Open a discussion or comment on any issue. We read everything.
MIT
