claude-code-hooks
10 hooks + 5 templates from 140+ hours of autonomous Claude Code operation.
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 claudecode-scan.
What's Included
Hooks (10)
| Hook | Purpose | Trigger |
|---|
context-monitor.sh | Graduated context window warnings (CAUTION → WARNING → CRITICAL → EMERGENCY) | PostToolUse |
activity-logger.sh | JSONL audit trail of every file change (path, lines added/deleted, timestamp) | PostToolUse (Edit|Write) |
syntax-check.sh | Automatic syntax validation after edits (Python, Shell, JSON, YAML, JS) | PostToolUse (Edit|Write) |
decision-warn.sh | Alerts on edits to sensitive paths without blocking | PreToolUse (Edit|Write) |
cdp-safety-check.sh | Blocks raw WebSocket CDP construction, forces use of proven tools | PreToolUse (Bash) |
proof-log-session.sh | Auto-generates 5W1H session summaries into daily markdown files | Stop, PreCompact |
session-start-marker.sh | Records session start time (used by proof-log) | PostToolUse |
no-ask-human.sh | Detects and discourages questions to absent humans during autonomous operation | PostToolUse |
branch-guard.sh | Blocks pushes to main/master branches without review | PreToolUse (Bash) |
error-gate.sh | Blocks external actions (push, publish, POST) when unresolved errors exist | PreToolUse (Bash) |
Templates (5)
| Template | Purpose |
|---|
CLAUDE-autonomous.md | Operational rules for autonomous execution: backup branches, loop detection, decision autonomy, state persistence |
dod-checklists.md | Definition of Done for code changes, publications, general tasks, and session handoffs |
task-queue.yaml | Structured task queue with priority, status tracking, and blocked items |
mission.md | Persistent state across session restarts: goals, progress, blockers, handoff notes |
LESSONS.md | Structured incident log: what failed, root cause, fix applied, prevention rule |
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 claudecode-scan's 20 checks:
| Dimension | Check | Covered By |
|---|
| Safety | PreToolUse blocks dangerous commands | cdp-safety-check.sh |
| Safety | API keys in dedicated files | CLAUDE-autonomous.md |
| Safety | Branch protection | branch-guard.sh |
| Safety | Error-aware gate | error-gate.sh |
| Quality | Syntax checks after edits | syntax-check.sh |
| Quality | Error detection and tracking | error-gate.sh + activity-logger.sh |
| Quality | Definition of Done checklist | dod-checklists.md |
| Quality | Output verification | CLAUDE-autonomous.md + dod-checklists.md |
| Monitoring | Context window alerts | context-monitor.sh |
| Monitoring | Activity logging | activity-logger.sh |
| Monitoring | Daily summaries | proof-log-session.sh |
| Recovery | Backup branches | CLAUDE-autonomous.md |
| Recovery | Watchdog for hangs/idle | (requires external tmux script) |
| Recovery | Loop detection | CLAUDE-autonomous.md |
| Autonomy | Task queue | task-queue.yaml |
| Autonomy | Block unnecessary questions | no-ask-human.sh |
| Autonomy | Persistent state | mission.md |
| Coordination | Decision audit trail | decision-warn.sh |
| Coordination | Multi-agent coordination | (requires external tooling) |
| Coordination | Lesson capture | LESSONS.md |
18/20 covered. The 2 uncovered checks (watchdog, multi-agent) require external tooling beyond hooks and templates.
Quick Setup
Option A: Install as Plugin (Recommended)
/plugin install claude-code-hooks@gaebalai/claude-code-hooks
That's it. All 10 hooks are automatically configured. No manual path editing, no settings.json changes.
After install, use the built-in skills:
/claude-code-hooks:setup — Choose your hook profile (minimal / standard / autonomous)/claude-code-hooks:diagnose — Check which hooks are active and healthy
Option B: Manual Setup
1. Copy hooks and templates
# Hooks
mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh
gaebalai
gaebalai
