One command to make Claude Code safe for autonomous operation. 667 example hooks · 9,200+ tests · 1,200+ installs/week · 日本語
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 · Hook Selector · Token Checkup · Cache Health · Version Check · CLAUDE.md Analyzer · All Tools · Recipes · Validate your settings.json · Check your score (npx cc-health-check) · Safety Audit
cc-safe-setup
Make Claude Code safe for autonomous operation
Prevents real incidents (from GitHub Issues):
✗ rm -rf deleted 3,467 files (~7 GB) without confirmation (#46058)
✗ 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
✗ CLAUDE.md rules silently ignored after context compaction
✗ Claude ran destructive DDL on production database (#46684)
✗ AI executed delete/kill operations on production environment (#46650)
✗ Subagents ignoring all CLAUDE.md rules since v2.1.84 (#40459)
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 user lost 3,467 files (~7 GB) when Claude ran rm -rf on their data directory without confirmation. Another 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. One user's Claude ran destructive DDL on a production database when asked only to investigate. Another had Claude execute delete and kill operations on production systems. 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. And CLAUDE.md rules get silently dropped after context compaction — your instructions vanish mid-session.
One user analyzed 6,852 sessions and found the Read:Edit ratio dropped from 6.6 to 2.0 — Claude editing files it never read jumped from 6% to 34%. That issue has over 2,100 reactions. The read-before-edit example hook catches this pattern before damage happens.
In April 2026, $1,446 was transferred without authorization when Claude moved funds between exchange accounts. A user lost $367 and got their account suspended from a Claude-generated script. Physical coordinates were uploaded to a public website despite 17 sessions of "no PII" in CLAUDE.md. And deny rules can be bypassed with 50+ subcommands.
Claude Code ships with no safety hooks by default. This tool fixes that. (Standalone guard script for quick setup | Database protection hooks | Credential protection hooks | Fabrication detection hook | Security vulnerability hooks)
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.
Works with subagents. Since v2.1.84, subagents and teammates don't receive CLAUDE.md — your project rules are silently skipped. Hooks operate at the process level, but subagent tool calls may bypass PreToolUse hooks in some configurations. As defense-in-depth, cc-safe-setup installs hooks at the user level (~/.claude/settings.json). The subagent-claudemd-inject example hook re-injects critical rules into subagent prompts.
| 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 |
#46058 #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 |
🛡️ Is your setup safe? Take the Security Checkup — 6 questions based on real incidents ($1,800+ in losses, April 2026).
📘 Tokens disappearing too fast? Take the free Token Checkup to diagnose where your tokens are going. Version Check: is your CC version affected by cache inflation (#46917)? Free CLAUDE.md templates optimized for cache efficiency. For the full guide: Token Book (¥2,500) — CLAUDE.md optimization, hook-based guards, context management, workflow design. 44,000 words from 800+ hours of operation. See also: Safety Guide (¥800, Chapter 3 free).
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>
Guards against issues that corrupt sessions or waste tokens silently.
| Hook | What It Solves | Issue |
|---|---|---|
cch-cache-guard |
Blocks reads of Claude session/billing files that poison prompt cache via cch= substitution |
#40652 |
image-file-validator |
Blocks Read of fake image files (text in .png) that permanently corrupt sessions | #24387 |
terminal-state-restore |
Restores Kitty keyboard protocol, cursor, bracketed paste on exit | #39096 #39272 |
large-read-guard |
Warns before reading large files via cat/less that waste context tokens |
#41617 |
prompt-usage-logger |
Logs every prompt with timestamps to track token consumption patterns | #41249 |
compact-alert-notification |
Alerts when auto-compaction fires (tracks compact-rebuild cycles that burn tokens) | #41788 |
token-budget-guard |
Blocks tool calls when estimated session cost exceeds a configurable threshold | #38335 |
session-index-repair |
Rebuilds sessions-index.json on exit so claude --resume finds all sessions |
#25032 |
session-backup-on-start |
Backs up session JSONL files on start (protects against silent deletion) | #41874 |
working-directory-fence |
Blocks Read/Edit/Write outside CWD (prevents operating on wrong project copy) | #41850 |
mcp-warmup-wait |
Waits for MCP servers to initialize on session start (fixes first-turn tool errors) | #41778 |
pre-compact-transcript-backup |
Full JSONL backup before compaction (protects against rate-limit data loss) | #40352 |
conversation-history-guard |
Blocks access to session JSONL files (prevents 20x cache poisoning) | #40524 |
read-before-edit |
Warns when Edit targets a file not recently Read (Read:Edit ratio dropped 70% — #42796) | #42796 |
replace-all-guard |
Warns/blocks Edit replace_all:true (prevents bulk data corruption) |
#41681 |
ripgrep-permission-fix |
Auto-fixes vendored ripgrep +x permission on start (fixes broken commands/skills) | #41933 |
| 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 667 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 |
Install safety hooks as Claude Code plugins — no npm required:
/plugin marketplace add yurukusa/cc-safe-setup
/plugin install safety-essentials@cc-safe-setup| Plugin | What it blocks |
|---|---|
safety-essentials |
rm -rf, force-push, hard-reset, .env overwrite, npm publish |
git-protection |
Force-push, main/master push, git clean, branch -D |
credential-guard |
.env write/edit, API keys in commands, service account files |
Also listed on claudemarketplaces.com.
| 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 limitations:
- 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-pmode. FileChangednotifications inject file contents into model context before hooks can intervene. If a sensitive file (.env,credentials.json) is modified externally during a session, its contents may appear in the conversation transcript regardless of hooks (#44909). Mitigation: usedotenv-watchto get alerted, and avoid editing sensitive files while Claude Code is running.
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+).
Starter Kit: Want hooks + settings + templates in one download? The Claude Code Safety Kit bundles 5 safety hooks, a pre-configured settings.json, CLAUDE.md templates, and 800-hour operation tips. Name your price ($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(#46684 #46650 #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.
- Token Book (¥2,500) — Cut token consumption in half. CLAUDE.md optimization, hook-based guards, context management, workflow design. 44,000 words with copy-paste templates. Buy on Ko-fi
- Safety Guide (¥800) — Token consumption diagnosis, file loss prevention, autonomous operation safety. From 800+ hours of real incidents. Chapter 3 free
- 800 Hours Operation Record (¥1,500) — Non-engineer running Claude Code autonomously for 800 hours. Failures, recovery, revenue reality. Chapter 2 free
- Wiki Guides: Token FAQ · CLAUDE.md Best Practices · Token Optimization
- 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 - Deny rules bypass vulnerability (Qiita) — 50+ subcommands disable all deny rules; hook-based defense
- 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
- settings.json Complete Template — copy-paste ready safety configuration
- First 3 Safety Steps — 5-minute safety setup from scratch
- CLAUDE.md Before/After — 40% token reduction through better writing patterns
- Token Savings Cheat Card — 5 techniques to cut consumption in half
- Token Consumption Checklist — 10-item diagnostic
- Outage Survival Kit — what to do when Claude Code is down
- CLAUDE.md Token Optimizer — 35-line template, 40% token reduction (800h tested)
- Worktree Safety Hooks — 3 hooks to protect against worktree deletion and cross-tree destruction
- Cache TTL Mitigation Guide — #46829 cache TTL change (1h→5m) impact and 4 mitigations
- Security Checkup Hooks — 4 hooks for financial, PII, deny bypass, and background task protection
- Cache Breakage Fix — 2 root causes of prompt cache invalidation (#47107 git status, #47098 session restart)
- CLAUDE.md Token Optimization Cheat Sheet — 5 CLAUDE.md patterns that reduce token consumption with before/after examples
- Token Troubleshooting Guide — fix quota drain, cache bugs, 1M context trap. Symptom-based diagnosis with latest issue references
- Token Optimization Guide (English) — 3 biggest token levers with hook code, practical walkthrough
- Token Book Sampler: 5 Techniques — free preview of the Token Book — 5 immediate techniques to reduce consumption
- Token Optimization Checklist — 10-step checklist to cut token consumption in half, with hook configs
- 3 Things That Actually Work — CLAUDE.md sizing, cache TTL, subagent control — based on 800h data
- Cache TTL Diagnostic — 3 patterns that break prompt cache + fixes
- Token Book Ch.1 Free Preview — Where are your Claude Code tokens going? The 4 layers of token consumption explained
- Deny Rules Break After 50 Subcommands — the hook that fixes Claude Code's deny rule bypass vulnerability
Need help configuring Claude Code safely? Safety Setup Service — audit, token optimization, and custom hooks by the cc-safe-setup team.
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.
Q: Hooks silently fail on macOS (Homebrew jq not found)
Claude Code runs hooks with a restricted PATH that excludes /opt/homebrew/bin (#46954). If jq is installed via Homebrew, hooks silently exit 0. Fix: add export PATH="/opt/homebrew/bin:$PATH" at the top of your hook script, or use absolute paths like /opt/homebrew/bin/jq. Inline hooks in settings.json may also be affected — add a PATH export prefix: export PATH="/opt/homebrew/bin:$PATH"; INPUT=$(cat); ...
Q: How is this different from claude-token-efficient?
Different goals. claude-token-efficient optimizes CLAUDE.md to make Claude's responses shorter and cheaper. cc-safe-setup prevents dangerous operations (file deletion, credential leaks, force-push). They work well together: use claude-token-efficient for cost reduction, cc-safe-setup for safety. For comprehensive token optimization beyond CLAUDE.md (hooks, context management, workflow design), see the Token Book.
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.
If cc-safe-setup saved you from a disaster (or just saved you time), a ⭐ helps others find it too.
- quiet life — Touch the dark. Something alive appears
- deep breath — Breathe with the light
- star moss — Drag to grow
MIT