After 108 hours of running Claude Code autonomously — 3,400+ sessions over 35 days — I had a pile of hooks that kept my AI from breaking things.
I just published them as a free, open-source collection.
github.com/yurukusa/claude-code-hooks
10 hooks. 5 operational templates. Everything has a "why it exists" story.
Why I Built This
I ran cc-health-check against my own Claude Code setup six weeks into autonomous operation. My score: 63/100.
Three major blind spots:
- No context window monitoring (my AI was silently losing memory)
- No activity logging (no audit trail of what ran when)
- No error detection from bash output (errors were silently ignored)
After fixing those: 95/100. Then I kept running into more failure modes. Each one produced a new hook.
These aren't hypothetical safeguards. Every hook exists because something actually went wrong.
The 10 Hooks
context-monitor.sh — The Most Important One
Why it exists: Session hit 3% context with no warning. Lost an hour of work when Claude started hallucinating from memory compression.
What it does: Graduated warnings as context fills up.
40% → CAUTION: Context filling up
25% → WARNING: Consider /compact soon
20% → CRITICAL: Recommend /compact now
15% → EMERGENCY: High risk of data loss
Configured as a PostToolUse hook — fires after every tool call.
activity-logger.sh — The Audit Trail
Why it exists: "What did Claude Code do in the last 3 hours?" needed an instant answer. There was none.
What it does: JSONL log of every Edit/Write operation with timestamp, file path, lines added/deleted.
{"ts":"2026-02-28T02:14:33Z","file":"/home/user/app.py","added":12,"deleted":3}
Feeds into cc-audit-log for human-readable reports.
syntax-check.sh — The Error Catcher
Why it exists: Claude would introduce a syntax error on line 47, continue editing 8 more files, then hit a wall trying to run the broken code. 20 minutes wasted each time.
What it does: Runs immediately after any file edit. Supports Python, Shell, JSON, YAML, JavaScript.
# PostToolUse on Edit|Write
python -m py_compile "$FILE" 2>&1
# or: node --check "$FILE"
# or: bash -n "$FILE"
Catches the error before Claude continues.
branch-guard.sh — The Production Protector
Why it exists: One accidental git push origin main during autonomous operation. Force-pushed an incomplete feature. Lost a day recovering.
What it does: Blocks push to main and master. Allows pushes to feature branches.
# BLOCKED:
git push origin main
git push --force origin master
# ALLOWED:
git push origin feature/new-thing
git push origin staging
Configurable via CC_PROTECT_BRANCHES="main:master:production".
error-gate.sh — The Publishing Blocker
Why it exists: Published a broken npm package while error logs showed unresolved failures. The gate between "run the code" and "push to production" was missing.
What it does: Blocks external actions (git push, npm publish, curl POST) when the error log has unresolved entries.
Local operations (file edits, test runs) still work. Only external publishing gets blocked.
no-ask-human.sh — The Autonomy Enforcer
Why it exists: Running Claude Code unattended. If it stops to ask "Should I use option A or B?" and no one's there, the session stalls.
What it does: Detects question patterns in output. Reminds Claude to decide and continue.
Detected: "Should I..."
→ Reminder: Decide autonomously. Pick based on existing conventions.
Essential for overnight runs.
decision-warn.sh — The Sensitive Path Alert
Why it exists: Claude editing ~/.claude/settings.json or ~/.bashrc without flagging it. Configuration drift with no audit trail.
What it does: Non-blocking alert when monitored paths are edited. Logs to decision-log. Doesn't block — just notifies.
⚠ DECISION: Editing monitored path: /home/user/.claude/hooks/syntax-check.sh
→ This action was logged.
proof-log-session.sh — The Session Recorder
Why it exists: "What did Claude Code accomplish today?" Daily summary generation was manual and got skipped.
What it does: Fires on session Stop. Aggregates activity-logger data into a 5W1H markdown summary.
## 2026-02-28 Session
**What:** 14 file edits, 3 git commits, 2 API calls
**Where:** /home/user/project
**How long:** 2h 14m
**Changed:** app.py (+47), config.json (+12), README.md (+8)
cdp-safety-check.sh — The WebSocket Blocker
Why it exists: Claude Code built a raw WebSocket connection to Chrome DevTools Protocol. Bypassed all safety layers. Caused a cascade of browser state corruption.
What it does: Blocks raw WebSocket CDP construction. Forces use of established tools (cdp-eval, cdp-daemon).
session-start-marker.sh — The Timer
Why it exists: proof-log-session.sh needs session duration. There was no start timestamp.
What it does: Records session start time to a temp file. Used by proof-log for duration calculation. Simple, boring, necessary.
The 5 Templates
Beyond hooks, I also included the operational documents that make autonomous operation possible:
| Template | Purpose |
|---|---|
CLAUDE-autonomous.md |
Rules for autonomous execution: backup branches, loop detection, state persistence |
dod-checklists.md |
Definition of Done checklists for code, publications, sessions |
task-queue.yaml |
Structured task queue with priority and status tracking |
mission.md |
Persistent state template for cross-session continuity |
LESSONS.md |
Incident log: what broke, root cause, fix applied |
The LESSONS.md template is underrated. Structured incident logs mean Claude Code doesn't repeat the same class of mistake across sessions.
Health Check Coverage
The collection covers 18 of 20 checks in cc-health-check:
| Dimension | Score |
|---|---|
| Safety | 4/4 (branch-guard, error-gate, cdp-safety, key storage) |
| Code Quality | 4/4 (syntax-check, error detection, DoD, verification) |
| Monitoring | 3/3 (context-monitor, activity-logger, proof-log) |
| Recovery | 2/3 (mission.md, LESSONS.md — watchdog not included) |
| Autonomy | 3/3 (task-queue, no-ask-human, mission.md) |
| Coordination | 2/3 (decision-warn, LESSONS.md — multi-agent not included) |
The 2 uncovered checks require external tooling (watchdog daemon, multi-agent coordination scripts).
Quick Start
git clone https://github.com/yurukusa/claude-code-hooks.git
cd claude-code-hooks
# Copy hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh
# Copy templates (pick what you need)
cp templates/mission.md ~/ops/
cp templates/LESSONS.md ~/
# Wire into settings.json
cat examples/settings.json
Then add the hooks section from examples/settings.json to your ~/.claude/settings.json.
Where This Came From
I run Claude Code 24/7 on WSL2. The system that generated this collection also generates session stats (cc-session-stats), audit logs (cc-audit-log), and health checks (cc-health-check).
Each hook in this collection represents a failure mode I actually hit. Context loss, accidental production pushes, silent errors, sessions stalled waiting for human input — all real problems, all now handled automatically.
Start with cc-health-check to see your score. Then use this kit to fix what's missing.
github.com/yurukusa/claude-code-hooks
My Claude Code setup score went from 63 to 95 after implementing these. What's yours?
Check: cc-health-check CLI or Web version
More tools: Dev Toolkit — 200 free browser-based tools for developers. JSON, regex, colors, CSS, SQL, and more. All single HTML files, no signup.
Top comments (0)