Troubleshooting

Click your problem. Follow the steps. Fixed in 2 minutes.

Quick fix for most problems: npx cc-safe-setup --quickfix

🔇 My hook doesn't fire

1. Is the hook file executable? ls -la ~/.claude/hooks/your-hook.sh

Fix: chmod +x ~/.claude/hooks/your-hook.sh

2. Does it have a shebang? First line must be #!/bin/bash

Fix: Add #!/bin/bash as the very first line

3. Is it registered in settings.json?

cat ~/.claude/settings.json | python3 -m json.tool | grep your-hook

Fix: npx cc-safe-setup --shield (auto-registers all hooks)

4. Is the matcher correct? "Bash" won't fire for Edit/Write

Use "" (empty) to match all tools, or "Edit|Write" for file ops

5. Is jq installed? which jq

Install: brew install jq (macOS) or sudo apt install jq (Linux)

6. Test it manually:

echo '{"tool_input":{"command":"rm -rf /"}}' | bash ~/.claude/hooks/your-hook.sh; echo "Exit: $?"

🚫 My hook blocks everything

Your regex pattern is too broad. Test with a safe command:

echo '{"tool_input":{"command":"ls -la"}}' | bash ~/.claude/hooks/your-hook.sh; echo "Exit: $?"

If it exits 2 for ls, your grep pattern matches too much.

Check the grep -qE pattern in your hook. Add \b word boundaries.

Example: grep -qE '\brm\s+.*-rf\s+/' instead of grep -q 'rm'

📋 Claude ignores CLAUDE.md rules

This is normal — CLAUDE.md rules degrade as context fills up.

Solution: Convert critical rules to hooks.

# Example: "Don't push to main" as a hook instead of a rule
npx cc-safe-setup  # Installs branch-guard

For any rule that must be enforced 100%, create a hook:

npx cc-safe-setup --create "your rule in plain English"

CLAUDE.md is for guidelines. Hooks are for hard constraints. Use both.

🔔 Too many permission prompts

Install auto-approve hooks for safe commands:

npx cc-safe-setup --install-example auto-approve-build    # npm test, cargo build
npx cc-safe-setup --install-example auto-approve-python   # pytest, mypy
npx cc-safe-setup --install-example auto-approve-git-read # git status, git log
npx cc-safe-setup --install-example compound-command-approver # cd && git log

Or add permissions in settings.json:

"permissions": {"allow": ["Bash(npm test)", "Bash(git status)", "Read(*)"]}

The --profile standard includes auto-approve hooks for common commands.

💾 settings.json won't parse

Validate:

python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"

Common causes: trailing commas, comments (JSON doesn't allow them), unescaped quotes

Auto-fix:

npx cc-safe-setup --quickfix

If totally broken: echo '{}' > ~/.claude/settings.json then re-run setup

🔄 Claude keeps retrying the same failed command

Install the error memory guard:

npx cc-safe-setup --install-example error-memory-guard

After 3 failures of the same command, it blocks and says "try a different approach".

Also useful: loop detector

npx cc-safe-setup --install-example loop-detector

💸 Session costs too much

Install token budget guard:

npx cc-safe-setup --install-example token-budget-guard

Warns at $10, blocks at $50 (configurable via CC_TOKEN_BUDGET and CC_TOKEN_BLOCK)

Monitor with:

npx cc-safe-setup --analyze

🧠 Context fills up too fast

Three hooks help:

npx cc-safe-setup --install-example output-length-guard   # Warn on large outputs
npx cc-safe-setup --install-example large-read-guard      # Warn before cat on large files
npx cc-safe-setup --install-example compact-reminder      # Suggest /compact after N calls

The context-monitor hook (installed by default) warns at 40%, 25%, 20%, 15%.

👥 Team members have different hook setups

Use project-level hooks:

npx cc-safe-setup --team
git add .claude/
git commit -m "chore: add team safety hooks"

Hooks are copied to .claude/hooks/ with relative paths. Works on any machine.

Generate CI to enforce:

npx cc-safe-setup --generate-ci

🔀 Hooks from different tools conflict

Analyze what you have:

npx cc-safe-setup --migrate-from manual  # See all existing hooks
npx cc-safe-setup --health               # Check hook health

Hooks in the same group run sequentially. If one consumes stdin, the next gets nothing.

Fix: Put each hook in a separate matcher group in settings.json.

Still stuck? npx cc-safe-setup --doctor — full diagnosis
npx cc-safe-setup --quickfix — auto-fix common issues
FAQ — 15 questions answered