cc-safe-setup

One command to make Claude Code safe for autonomous operation. 639 example hooks · 13,943 tests · 1,000+ installs/day · 日本語

npx cc-safe-setup

Installs 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.

Why This Exists

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.

What Gets Installed

Each hook exists because a real incident happened without it.

v2.1.85: if Field Support

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.

PermissionRequest Hooks (NEW)

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.

Install any of these: npx cc-safe-setup --install-example <name>

All 49 Commands

Quick Start by Scenario

Common Pain Points (from GitHub Issues)

How It Works

1. Writes hook scripts to ~/.claude/hooks/
2. Updates ~/.claude/settings.json to register the hooks
3. 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.

Before / After

Run npx cc-health-check to see the difference:

Configuration

After Installing

Verify your setup:

npx cc-health-check

Full Kit

cc-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

Examples

Safety Audit

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 --audit

Analyzes 9 safety dimensions and gives you a score (0-100) with one-command fixes for each risk.

CI Integration (GitHub Action)

# .github/workflows/safety.yml
- uses: yurukusa/cc-safe-setup@main
  with:
    threshold: 70  # CI fails if score drops below this

Project Scanner

npx cc-safe-setup --scan         # detect tech stack, recommend hooks
npx cc-safe-setup --scan --apply # auto-create CLAUDE.md with project rules

Create Hooks from Plain English

npx 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.

Self-Learning Safety

npx cc-safe-setup --learn        # analyze your block history for patterns
npx cc-safe-setup --learn --apply # auto-generate custom hooks from patterns

Examples

Need custom hooks beyond the 8 built-in ones? Install any example with one command:

npx cc-safe-setup --install-example block-database-wipe

Or browse all available examples in examples/:

• auto-approve-git-read.sh — Auto-approve git status, git log, even with -C flags
• 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, Django flush, Rails db:drop, raw DROP 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 --global modifications 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 push when 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-*-cwd files 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.md on 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

SAFETY_CHECKLIST.md — Copy-paste checklist for before/during/after autonomous sessions.

Windows Support

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 --doctor

This detects Windows backslash paths (C:\Users\... → C:/Users/...) and missing execute permissions.

See Issue #1 for details.

Troubleshooting

TROUBLESHOOTING.md — "Hook doesn't work" → step-by-step diagnosis. Covers every common failure pattern.

settings.json Reference

SETTINGS_REFERENCE.md — Complete reference for permissions, hooks, modes, and common configurations. Includes known limitations and workarounds.

Migration Guide

MIGRATION.md — Step-by-step guide for moving from permissions-only to permissions + hooks. Keep your existing config, add safety layers on top.

Learn More

• 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 if field 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

FAQ

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.

Contributing

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 -n syntax validation passing

Share your experience: Used cc-safe-setup and have feedback? Open a discussion or comment on any issue. We read everything.

License

MIT