Hooks Automation skill for Claude Code

# Hook recipes

Tested patterns to adapt. Each lists the settings entry and the script. Scripts read the
hook JSON from stdin. Put them in `.claude/hooks/` and `chmod +x` them.

Contents:
1. Format the edited file (PostToolUse)
2. Guard dangerous Bash commands (PreToolUse)
3. Protect paths from edits (PreToolUse)
4. Run tests before Claude stops (Stop)
5. Desktop notification when Claude is waiting (Notification)
6. Inject context at session start (SessionStart)
7. Block secrets pasted into prompts (UserPromptSubmit)
8. Audit log of shell commands (PreToolUse)

## 1. Format the edited file

```json
{ "matcher": "Edit|Write|MultiEdit",
  "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.py", "timeout": 30 }] }
```

```python
#!/usr/bin/env python3
import json, os, shutil, subprocess, sys

data = json.load(sys.stdin)
path = (data.get("tool_input") or {}).get("file_path", "")
if not path or not os.path.isfile(path):
    sys.exit(0)
ext = os.path.splitext(path)[1].lower()
cmds = {
    (".ts", ".tsx", ".js", ".jsx", ".json", ".css", ".md", ".yml", ".yaml"): ["npx", "--no-install", "prettier", "--write", path],
    (".py",): ["ruff", "format", path],
    (".go",): ["gofmt", "-w", path],
    (".rs",): ["rustfmt", path],
}
for exts, cmd in cmds.items():
    if ext in exts and shutil.which(cmd[0]):
        r = subprocess.run(cmd, capture_output=True, text=True, timeout=25)
        if r.returncode != 0:
            print(f"formatter failed on {path}: {r.stderr.strip()[:500]}", file=sys.stderr)
            sys.exit(2)  # feed the error back to Claude so it fixes the syntax
sys.exit(0)
```

Use `--no-install` so a missing local prettier never triggers a download on every edit.

## 2. Guard dangerous Bash commands

```json
{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard_bash.py" }] }
```

```python
#!/usr/bin/env python3
import json, re, sys

try:
    cmd = json.load(sys.stdin)["tool_input"]["command"]
except Exception:
    sys.exit(0)  # not a Bash payload; do not block

RULES = [
    (r"\brm\s+-[a-z]*r[a-z]*f?\s+(/|~|\$HOME)/?(\s|$)", "recursive delete of / or home"),
    (r"\bgit\s+push\b.*(--force\b|-f\b)(?!-with-lease)", "force push; use --force-with-lease after asking the user"),
    (r"\bgit\s+reset\s+--hard\b", "hard reset discards work; ask the user first"),
    (r"(curl|wget)[^|]*\|\s*(sudo\s+)?(sh|bash|zsh)\b", "piping a download into a shell"),
    (r"\b(DROP\s+(TABLE|DATABASE)|TRUNCATE)\b", "destructive SQL; ask the user first"),
    (r"\bchmod\s+-R\s+777\b", "world-writable permissions"),
    (r"\b(cat|less|head|tail|cp|scp)\b[^|;&]*\.env(\.|\s|$)", "reading .env secrets through the shell"),
]
for pattern, why in RULES:
    if re.search(pattern, cmd, re.IGNORECASE):
        print(f"Blocked: {why}. Command: {cmd[:200]}", file=sys.stderr)
        sys.exit(2)
sys.exit(0)
```

Regex guards are a safety net, not a sandbox. Pair with permission deny rules and, for
untrusted work, the Bash sandbox.

## 3. Protect paths from edits

```json
{ "matcher": "Edit|Write|MultiEdit|NotebookEdit",
  "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect_paths.py" }] }
```

```python
#!/usr/bin/env python3
import fnmatch, json, os, sys

PROTECTED = [".env", ".env.*", "*.pem", "package-lock.json", "pnpm-lock.yaml",
             "migrations/applied/*", ".github/workflows/*", "generated/*"]
data = json.load(sys.stdin)
path = (data.get("tool_input") or {}).get("file_path") or (data.get("tool_input") or {}).get("notebook_path", "")
root = os.environ.get("CLAUDE_PROJECT_DIR", data.get("cwd", ""))
rel = os.path.relpath(path, root) if path else ""
if rel.startswith(".."):
    print(f"Blocked: {path} is outside the project.", file=sys.stderr); sys.exit(2)
for pat in PROTECTED:
    if fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(os.path.basename(rel), pat):
        print(f"Blocked: {rel} is protected ({pat}). Explain the needed change to the user instead.", file=sys.stderr)
        sys.exit(2)
sys.exit(0)
```

## 4. Run tests before Claude stops

```json
"Stop": [{ "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require_tests.py", "timeout": 300 }] }]
```

```python
#!/usr/bin/env python3
import json, subprocess, sys

data = json.load(sys.stdin)
if data.get("stop_hook_active"):
    sys.exit(0)  # already continued once because of this hook; never loop
# Only run when files changed in this repo
changed = subprocess.run(["git", "status", "--porcelain"], capture_output=True, text=True).stdout.strip()
if not changed:
    sys.exit(0)
r = subprocess.run(["npm", "test", "--silent"], capture_output=True, text=True, timeout=280)
if r.returncode != 0:
    tail = "\n".join((r.stdout + r.stderr).strip().splitlines()[-40:])
    print(f"Tests fail; fix them before finishing:\n{tail}", file=sys.stderr)
    sys.exit(2)
sys.exit(0)
```

Keep the test command fast (affected tests only) or this hook makes every turn slow.

## 5. Desktop notification when Claude is waiting

Put this in `~/.claude/settings.json` (personal, not team):

```json
"Notification": [{ "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/notify.py" }] }]
```

```python
#!/usr/bin/env python3
import json, platform, shutil, subprocess, sys

msg = json.load(sys.stdin).get("message", "Claude Code needs your attention")
if platform.system() == "Darwin":
    safe = msg.replace('"', "'")
    subprocess.run(["osascript", "-e", f'display notification "{safe}" with title "Claude Code"'])
elif shutil.which("notify-send"):
    subprocess.run(["notify-send", "Claude Code", msg])
```

## 6. Inject context at session start

```json
"SessionStart": [{ "matcher": "startup|resume", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/context.sh" }] }]
```

```sh
#!/bin/sh
# stdout becomes context. Keep it under ~30 lines.
echo "Branch: $(git branch --show-current 2>/dev/null)"
echo "Uncommitted files: $(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')"
[ -f .claude/handoff.md ] && { echo "--- handoff.md ---"; head -40 .claude/handoff.md; }
exit 0
```

## 7. Block secrets pasted into prompts

```json
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/prompt_secrets.py" }] }]
```

```python
#!/usr/bin/env python3
import json, re, sys

prompt = json.load(sys.stdin).get("prompt", "")
patterns = [r"sk-[A-Za-z0-9_-]{20,}", r"AKIA[0-9A-Z]{16}", r"gh[pousr]_[A-Za-z0-9]{30,}",
            r"-----BEGIN [A-Z ]*PRIVATE KEY-----"]
if any(re.search(p, prompt) for p in patterns):
    print("Prompt blocked: it contains what looks like a credential. Remove it and rotate the key.", file=sys.stderr)
    sys.exit(2)
sys.exit(0)
```

## 8. Audit log of shell commands

```json
{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/audit.py" }] }
```

```python
#!/usr/bin/env python3
import json, os, sys, time

d = json.load(sys.stdin)
line = {"ts": time.strftime("%Y-%m-%dT%H:%M:%S"), "session": d.get("session_id"),
        "cwd": d.get("cwd"), "cmd": (d.get("tool_input") or {}).get("command")}
with open(os.path.expanduser("~/.claude/bash-audit.jsonl"), "a") as f:
    f.write(json.dumps(line) + "\n")
sys.exit(0)
```

Rotate or cap the log file; it grows with every command.