# Hooks & Automation

## Why This Matters

Hooks are the #1 "why didn't I do this sooner" recommendation across the community. Unlike CLAUDE.md rules (which Claude can forget mid-session), hooks **always execute**. They provide deterministic guardrails around non-deterministic AI behaviour.

Key principle: "Never send an LLM to do a linter's job. LLMs are expensive and slow compared to traditional linters."

## Current State

- No hooks configured in `~/.claude/settings.json`
- Formatting/linting rules live in CLAUDE.md as prose instructions

## Community Recommendations

### PostToolUse: Auto-Formatting

Run formatters automatically after every `Edit`/`Write` tool call. Eliminates all formatting rules from CLAUDE.md.

- `prettier --write` for JS/TS/JSON/YAML/MD
- `shfmt -w` for shell scripts
- `ruff format` for Python
- Plugin: `ryanlewis/claude-format-hook` supports multi-language detection

Configuration goes in `~/.claude/settings.json` under `hooks.PostToolUse`.

### PreToolUse: Security Gates

Block dangerous operations before they execute:

- Block writes to `.env`, `.key`, `.pem`, `secrets/`, lockfiles
- Block destructive commands (`rm -rf /`, `dd`, `mkfs`)
- Scan for API keys/credentials in file content before writes
- Block commits that include sensitive file patterns

### PreToolUse: Commit Validation

Wrap `Bash(git commit)` with test/lint validation. Only allow commits if checks pass. Forces Claude into "test-and-fix" loops until the build is green. This is considered the single most effective quality gate.

Important: **Don't block at write time** — blocking on `Edit`/`Write` confuses Claude mid-plan. Validate at commit time instead.

### PreCompact: Transcript Backup

Save conversation transcript before auto-compaction so context is never lost. Creates a timestamped backup in a known location. Pairs well with the auto-memory system.

Reference: https://yuanchang.org/en/posts/claude-code-auto-memory-and-hooks/

### Notification Hook

Desktop notifications when Claude finishes a long task or needs input. Useful when running background agents.

Plugin: `CC Notify` from awesome-claude-code.

## Anti-Patterns

- Don't add too many hooks — each one adds latency to every tool call
- Don't block on `Edit`/`Write` for linting — do it on `PostToolUse` (non-blocking) or at commit time
- Don't duplicate hook logic in CLAUDE.md — if a hook handles it, remove the prose rule