๐ŸŽฉ You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP โ†’
Sign In

cc-safe-setup

Package Overview
Dependencies
Maintainers
1
Versions
252
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

cc-safe-setup

One command to make Claude Code safe. 701 example hooks + 8 built-in. 56 CLI commands. Token consumption diagnosis. Works with Auto Mode.

latest
Source
npmnpm
Version
29.8.0
Version published
Weekly downloads
33
-88.85%
Maintainers
1
Weekly downloads
ย 
Created
Source

cc-safe-setup

npm version npm downloads tests

๐Ÿš€ Launching on Product Hunt โ€” April 21! Follow us and upvote to support open source safety for AI coding agents.

One command to make Claude Code safe for autonomous operation. 701 example hooks ยท 9,200+ tests ยท 30K+ total installs ยท ๆ—ฅๆœฌ่ชž

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 npm dependencies. Hooks use jq at runtime (brew install jq / apt install jq).

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 ยท Incident Tracker ยท 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 permanently destroyed ~50 GB / 1,500 files (#49129) โ† April 2026
  โœ— Auto mode approved ~/.ssh deletion โ€” all SSH keys gone (#49554)
  โœ— ~/.git-credentials PATs deleted without confirmation (#49539)
  โœ— 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.

Why This Exists

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.

๐Ÿšจ Opus 4.7 Crisis (April 2026)

Opus 4.7 broke auto mode's safety classifier โ€” it was hardcoded to Opus 4.6. If you use auto mode with Opus 4.7, dangerous commands run without the built-in safety check. In 3 days: 50 GB permanently deleted, ~/.ssh wiped, git credentials destroyed, shell configs truncated to 0 bytes. Users report 4x token consumption from silent model switches.

One command to fix it:

npx cc-safe-setup --opus47

Installs 4 hooks targeting known Opus 4.7 regressions. Full details โ†’ ยท Emergency Defense Kit (Gist) ยท Safety Scanner

What Gets Installed

HookPreventsRelated Issues
Destructive Guardrm -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 GuardPushes to main/master + force-push (--force) on all branches
Secret Guardgit add .env, credential files, git add . with .env present#6527
Syntax CheckPython, Shell, JSON, YAML, JS errors after edits
Context MonitorSession state loss from context window overflow (40%โ†’25%โ†’20%โ†’15% warnings)
Comment StripperBash comments breaking permission allowlists#29582
cd+git Auto-ApproverPermission prompt spam for cd /path && git log#32985 #16561
API Error AlertSilent session death from rate limits or API errors โ€” desktop notification + log

Each hook exists because a real incident happened without it.

Free diagnostic tools

ToolWhat it does
Token Checkup5 questions โ†’ find where your tokens are going (30 seconds)
Security Checkup6 questions based on real incidents ($1,800+ in losses)
Version CheckIs your CC version affected by cache inflation?

Go deeper

ResourceWhat you getPrice
Token BookCut token consumption in half. CLAUDE.md templates, hook configs, context management, 32 failure patterns with fixes. 44,000+ words from 800+ hours of real operation data.ยฅ2,500 (~$17). Ch.1 free
Safety GuideEnd-to-end Claude Code safety setup. From first install to overnight autonomous runs.ยฅ800 (~$5). Ch.3 free

Why pay? A Max plan costs $200/month. One token waste incident burns 50โ€“80% of your weekly quota in hours (#46727). One rm -rf incident costs days of recovery. The Token Book costs less than 2 hours of Max subscription time โ€” and the CLAUDE.md templates alone can reduce consumption by 40%.

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.

HookWhat It SolvesIssue
quoted-flag-approver"Quoted characters in flag names" prompt on git commit -m "msg"#27957
bash-heuristic-approverSafety heuristic prompts for $(), backticks, ANSI-C quoting#30435
edit-always-allowEdit prompts in .claude/skills/ despite bypassPermissions#36192
allow-git-hooks-dirEdit prompts in .git/hooks/ for pre-commit/pre-push setup
allow-protected-dirsAll protected directory prompts (CI/Docker environments)#36168
git-show-flag-sanitizerStrips invalid --no-stat from git show (wastes context on error)#13071
compact-blockerBlocks auto-compaction via PreCompact (preserves full context)#6689
webfetch-domain-allowAuto-approves WebFetch by domain (fixes broken domain:* wildcard)#9329

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

Session Protection Hooks

Guards against issues that corrupt sessions or waste tokens silently.

HookWhat It SolvesIssue
cch-cache-guardBlocks reads of Claude session/billing files that poison prompt cache via cch= substitution#40652
image-file-validatorBlocks Read of fake image files (text in .png) that permanently corrupt sessions#24387
terminal-state-restoreRestores Kitty keyboard protocol, cursor, bracketed paste on exit#39096 #39272
large-read-guardWarns before reading large files via cat/less that waste context tokens#41617
prompt-usage-loggerLogs every prompt with timestamps to track token consumption patterns#41249
compact-alert-notificationAlerts when auto-compaction fires (tracks compact-rebuild cycles that burn tokens)#41788
token-budget-guardBlocks tool calls when estimated session cost exceeds a configurable threshold#38335
session-index-repairRebuilds sessions-index.json on exit so claude --resume finds all sessions#25032
session-backup-on-startBacks up session JSONL files on start (protects against silent deletion)#41874
working-directory-fenceBlocks Read/Edit/Write outside CWD (prevents operating on wrong project copy)#41850
mcp-warmup-waitWaits for MCP servers to initialize on session start (fixes first-turn tool errors)#41778
pre-compact-transcript-backupFull JSONL backup before compaction (protects against rate-limit data loss)#40352
conversation-history-guardBlocks access to session JSONL files (prevents 20x cache poisoning)#40524
read-before-editWarns when Edit targets a file not recently Read (Read:Edit ratio dropped 70% โ€” #42796)#42796
replace-all-guardWarns/blocks Edit replace_all:true (prevents bulk data corruption)#41681
ripgrep-permission-fixAuto-fixes vendored ripgrep +x permission on start (fixes broken commands/skills)#41933

All 49 Commands

CommandWhat It Does
npx cc-safe-setupInstall 8 safety hooks
--create "desc"Generate hook from plain English
--audit [--fix|--json|--badge]Safety score 0-100
--lintStatic analysis of config
--diff <file>Compare settings
--compare <a> <b>Side-by-side hook comparison
--migrateDetect hooks from other projects
--generate-ciCreate GitHub Actions workflow
--shareGenerate shareable URL
--benchmarkMeasure hook speed
--dashboardReal-time terminal UI
--issuesGitHub Issues each hook addresses
--doctorDiagnose hook problems
--watchLive blocked command feed
--statsBlock history analytics
--learn [--apply]Pattern learning
--scan [--apply]Tech stack detection
--export / --importTeam config sharing
--verifyTest each hook
--install-example <name>Install from 701 examples
--examples [filter]Browse examples by keyword
--fullAll-in-one setup
--statusCheck installed hooks
--dry-runPreview changes
--uninstallRemove all hooks
--shieldMaximum safety in one command
--guard "rule"Instantly enforce a rule from English
--suggestPredict risks from project analysis
--from-claudemdConvert CLAUDE.md rules to hooks
--teamProject-level hooks for git sharing
--profile [level]Switch safety profiles
--save-profile <name>Save current hooks as profile
--analyzeSession analysis dashboard
--healthHook health table
--quickfixAuto-fix common problems
--replayVisual 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-projectFull project setup (hooks + CLAUDE.md + CI)
--scoreCI-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
--validateValidate all hook scripts (syntax + structure)
--safe-modeMaximum protection: all safety hooks + strict config
--changelogShow what changed in each version
--reportGenerate safety report
--helpShow help

Quick Start by Scenario

I want to...Command
Make Claude Code safe right nownpx cc-safe-setup --shield
Stop permission prompt spamnpx cc-safe-setup --install-example auto-approve-readonly
Enforce a rule instantlynpx cc-safe-setup --guard "never delete production data"
See what risks my project hasnpx cc-safe-setup --suggest
Convert CLAUDE.md rules to hooksnpx cc-safe-setup --from-claudemd
Share hooks with my teamnpx cc-safe-setup --team && git add .claude/
Choose a safety levelnpx cc-safe-setup --profile strict
See what Claude blocked todaynpx cc-safe-setup --replay
Know why a hook existsnpx cc-safe-setup --why destructive-guard
Block silent memory file editsnpx cc-safe-setup --install-example memory-write-guard
Stop built-in skills editing opaquelynpx cc-safe-setup --install-example skill-gate
Diagnose why hooks aren't workingnpx cc-safe-setup --doctor
Preview how hooks react to a commandnpx cc-safe-setup --simulate "git push origin main"
Protect a specific file from editsnpx cc-safe-setup --protect .env
Stop .git/ write promptsnpx cc-safe-setup --install-example allow-git-hooks-dir
Auto-approve compound git commandsnpx cc-safe-setup --install-example auto-approve-compound-git
Detect prompt injection patternsnpx cc-safe-setup --install-example prompt-injection-detector
Define rules in YAML, compile to hooksnpx cc-safe-setup --rules rules.yaml
Validate all hook scripts are correctnpx cc-safe-setup --validate
Maximum protection modenpx cc-safe-setup --safe-mode
Migrate from Cursor/WindsurfMigration Guide

Plugin Marketplace

Install safety hooks as Claude Code plugins โ€” no npm required:

/plugin marketplace add yurukusa/cc-safe-setup
/plugin install safety-essentials@cc-safe-setup
PluginWhat it blocks
safety-essentialsrm -rf, force-push, hard-reset, .env overwrite, npm publish
git-protectionForce-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.

Common Pain Points (from GitHub Issues)

ProblemIssueFix
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

How It Works

  • Writes hook scripts to ~/.claude/hooks/
  • Updates ~/.claude/settings.json to 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 -p mode.
  • FileChanged notifications 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: use dotenv-watch to get alerted, and avoid editing sensitive files while Claude Code is running.

Before / After

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

BeforeAfter
Safety Guards25%75%
Overall Score50/10095/100
Destructive commandsUnprotectedBlocked
Force pushAllowedBlocked
.env in gitPossibleBlocked
Context warningsNone4-stage alerts

Configuration

VariableHookDefault
CC_ALLOW_DESTRUCTIVE=1destructive-guard0 (protection on)
CC_SAFE_DELETE_DIRSdestructive-guardnode_modules:dist:build:.cache:__pycache__:coverage
CC_PROTECT_BRANCHESbranch-guardmain:master
CC_ALLOW_FORCE_PUSH=1branch-guard0 (protection on)
CC_SECRET_PATTERNSsecret-guard.env:.env.local:credentials:*.pem:*.key
CC_CONTEXT_MISSION_FILEcontext-monitor$HOME/mission.md

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+).

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

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 (#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 --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

Free Gists

Professional Services

Need help configuring Claude Code safely? Safety Setup Service โ€” audit, token optimization, and custom hooks by the cc-safe-setup team.

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.

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.

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.

If cc-safe-setup saved you from a disaster (or just saved you time), a โญ helps others find it too.

Also by yurukusa

License

MIT

Keywords

claude-code

FAQs

Package last updated on 20 Apr 2026

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts