claude-code-hooks

⚠️ This repository has moved to cc-safe-setup — 677 hooks, 9,200+ tests, one-command install. This repo (16 hooks) is the original version kept for backward compatibility.

Quick Start (New Repository)

npx cc-safe-setup            # Install 8 essential hooks in 10 seconds
npx cc-safe-setup --verify   # Test each hook works

677 Example Hooks | Interactive Hook Selector | Token Checkup (diagnose token waste)

Spending too much on Claude Code? The average developer spends $13/day on tokens. Our Token Book shows how to cut that in half with real data from 800+ hours of operation.

Original Repository (16 hooks)

Interactive Cookbook — search, filter, and copy 26 hook recipes in your browser.

16 hooks + 6 templates from 700+ hours of autonomous Claude Code operation.

┌─────────────────────────────────────────────────────────┐
│                   Claude Code Session                    │
│                                                         │
│  User Prompt ──→ PermissionRequest ──→ PreToolUse       │
│                  (auto-approve-      (destructive-guard  │
│                   readonly)           branch-guard       │
│                                       comment-strip      │
│                                       cd-git-allow        │
│                                       secret-guard)       │
│                         │                   │            │
│                         ▼                   ▼            │
│                    Tool Executes ──→ PostToolUse          │
│                                     (syntax-check        │
│                                      context-monitor     │
│                                      activity-logger     │
│                                      tmp-cleanup)        │
│                         │                                │
│                         ▼                                │
│                   Session End ──→ Stop                    │
│                                  (proof-log-session)     │
│                                                         │
│  Notification ──→ no-ask-human                           │
│  PreCompact   ──→ proof-log-session                      │
└─────────────────────────────────────────────────────────┘

Production infrastructure for running Claude Code autonomously. Every hook exists because something went wrong without it. Every template encodes a workflow pattern that survived real-world autonomous operation.

Honest disclaimer: This is what works for us. Your workflow may differ. These hooks and templates address the failure modes we actually encountered.

Covers 18 of 20 checks in cc-health-check.

Get Started in 10 Seconds

npx cc-safe-setup            # Install 8 essential hooks
npx cc-safe-setup --verify   # Test each hook works
npx cc-safe-setup --doctor   # Diagnose any issues
npx cc-safe-setup --create "block npm publish without tests"  # Generate custom hooks

Want 677 hooks? Use cc-safe-setup — the successor to this repo with 40x more hooks, comprehensive tests, and one-command install.

New to hooks? Read the Troubleshooting Guide or print the Cheat Sheet.

Losing tokens too fast? Token Book — real optimization data from 800+ hours (¥2,500, Chapter 1 free).

What's Included

Hooks (16)

Templates (5)

Example Configurations (3)

• settings-minimal.json — Context monitor + syntax check. Good starting point.
• settings.json — Recommended setup with all core hooks.
• settings-autonomous.json — Full autonomous mode with no-ask-human + branch guard + error gate.

Health Check Coverage

How the kit maps to cc-health-check's 20 checks:

18/20 covered. The 2 uncovered checks (watchdog, multi-agent) require external tooling beyond hooks and templates.

Quick Setup

Option A: Quick Install (Recommended)

npx cc-safe-setup

Installs 8 essential hooks in 10 seconds. Zero config. Details

After install, verify hooks are working:

npx cc-safe-setup --verify   # Test each hook with sample inputs
npx cc-safe-setup --status   # Check which hooks are installed
npx cc-health-check          # Full setup diagnostic (20 checks)

Note: cc-safe-setup installs hooks (automatic background scripts), not skills or plugins. Hooks activate immediately after restarting Claude Code — no additional commands needed.

Option B: Manual Setup

1. Copy hooks and templates

# Hooks
mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# Templates (copy what you need to your project)
cp templates/CLAUDE-autonomous.md ~/CLAUDE.md          # or append to existing
cp templates/dod-checklists.md ~/.claude/
cp templates/task-queue.yaml ~/ops/
cp templates/mission.md ~/ops/
cp templates/LESSONS.md ~/

2. Wire hooks into settings.json

Open ~/.claude/settings.json and add the hooks configuration. Use one of the example files as a starting point:

cat examples/settings-autonomous.json

Then copy the "hooks" section into your own settings file, replacing /path/to/hooks/ with your actual path.

Minimal example (context monitor + syntax check only):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/context-monitor.sh" }]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/syntax-check.sh" }]
      }
    ]
  }
}

3. Verify

Start a Claude Code session and make an edit. You should see syntax check output (on error) and context monitoring messages (when context drops below thresholds).

Hook Details

context-monitor.sh

The most valuable hook in this collection.

Monitors remaining context window capacity. Falls back to tool-call-count estimation when debug logs are unavailable.

Why it exists: We lost an entire session's work when context hit 3% with no warning.

Thresholds: 40% CAUTION → 25% WARNING → 20% CRITICAL (auto-compact) → 15% EMERGENCY

activity-logger.sh

Records every Edit/Write operation to JSONL with timestamp, file path, and line counts.

Why it exists: "What did Claude Code do in the last 2 hours?" needs an instant answer.

syntax-check.sh

Runs syntax validation immediately after Claude Code edits a file. Supports Python, Shell, JSON, YAML, JS.

Why it exists: Claude Code would introduce a syntax error, continue working for 10+ steps, then hit a wall.

branch-guard.sh

Blocks git push to main/master. Allows pushes to feature/staging branches.

Why it exists: One accidental force-push to main destroyed a day of work.

Config: CC_PROTECT_BRANCHES="main:master:production" (default: main:master)

error-gate.sh

Blocks external actions (git push, npm publish, curl POST) when unresolved errors exist in the error log. Allows local operations.

Why it exists: Publishing broken code to production while errors were unresolved.

Config: CC_ERROR_LOG (default: ~/.claude/error-tracker.log), CC_ERROR_THRESHOLD (default: WARNING)

decision-warn.sh

Non-blocking alerts when Claude Code edits files in monitored directories.

cdp-safety-check.sh

Blocks raw Chrome DevTools Protocol WebSocket construction. Forces use of established tools.

proof-log-session.sh

Generates 5W1H session summary at session end. Aggregates from activity-logger.sh.

session-start-marker.sh

Records session start timestamp. Used by proof-log for duration calculation.

no-ask-human.sh

Detects question patterns and reminds the agent to decide autonomously. Essential for unattended operation.

Environment Variables

Requirements

• Claude Code (with hooks support)
• bash + jq
• python3 (used by activity-logger, proof-log, context-monitor)
• Optional: PyYAML (YAML syntax checking), Node.js (JS syntax checking)

Common Accidents & Prevention

Real incidents from GitHub Issues, and the hooks that prevent them:

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

Cookbook

COOKBOOK.md — 18 ready-to-use hook recipes from real GitHub Issues. Auto-approve git with -C flags, SSH commands, desktop notifications, test enforcement, PowerShell protection, database wipe prevention, dotfile protection, auto-checkpoint, git config guard, and more.

Troubleshooting

Hooks not firing?

1. Use absolute paths in your hook commands. Relative paths break depending on which directory you start Claude Code from:

   "command": "bash ~/.claude/hooks/syntax-check.sh"
   

2. Test your hook in isolation before relying on it:

   echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | bash ~/.claude/hooks/decision-warn.sh
   echo $?  # Should print 2 (blocked) for dangerous commands
   

3. Check the timeout. Hooks have a 5-second timeout by default. If your script does anything slow (network calls, large file scans), it may silently time out and Claude proceeds as if it passed.

4. Verify permissions: chmod +x hooks/*.sh — hooks must be executable.

5. VS Code extension: Hooks configured in settings.json may not fire in the VS Code extension. Test with the CLI first: claude from terminal.

6. Exit codes matter:

   • exit 0 = allow (hook passed)
   • exit 2 = hard block (command never runs — Claude cannot override this)
   • Any stderr output on exit 2 is shown to Claude as the reason

Related Tools

Run cc-health-check first to see your score, then use this kit to fix what's missing.

Want it all set up in 15 minutes?

Claude Code Ops Kit (Pay What You Want) — Everything above, pre-configured and ready to deploy:

• All 16 hooks, pre-configured with install.sh
• 6 templates (CLAUDE.md baseline + autonomous, DoD checklists, task-queue, mission, LESSONS)
• 3 exclusive tools (watchdog, CLAUDE.md generator, risk-score)
• 3 settings.json presets (minimal / standard / autonomous)

Free version = parts. Ops Kit = assembled, tested, ready to run.

New to hooks? See the Migration Guide — step-by-step from permissions-only to permissions + hooks.

📘 Want the full story? Production guide from 700+ hours of autonomous operation — everything that broke, and how we fixed it.

📰 Popular articles:

• Skills Guide deep-dive (19K+ views) — Anthropic's official Skills PDF analyzed
• 108 hours running unattended — every incident and the safety hooks that came from them

If these hooks saved you from a bad day, consider giving this repo a ⭐ — it helps others find it.

License

MIT License.