Claude Code Hooks Cookbook: 12 Automations Solo Founders Ship

By Rakshit Yadav (@yadavrakshit60)•Nov 2026•11 min read

Short answer: this is a recipe book, not a reference — 12 copy-paste .claude/settings.json hooks grouped by job (formatting, safety, notifications, CI) rather than by event type, so you can grab the one that matches what you're trying to automate right now without reading the whole hooks spec first. If you want the event mechanics and exit-code rules first, our hooks examples post covers those in depth; this one assumes you already know a PreToolUse hook can block and just want the scripts.

Solo founders running Claude Code tend to hit the same four automation needs in roughly this order: stop the formatter nagging you, stop a destructive command before it runs, get pinged when a long build finishes, and stop a broken build from merging. The 12 recipes below map to exactly those four jobs, three recipes each, plus a cheat table and a merged settings template at the end so you don't have to hand-assemble the JSON yourself.

Hook event cheat table

EventFires whenCan block?Typical use
PreToolUseBefore a tool call runsYes — exit 2Guardrails: secrets, destructive commands, protected branches
PostToolUseAfter a tool call completesNo (turn-level only)Formatting, linting, auto-test, logging
NotificationClaude is waiting on inputNoDesktop/sound alerts
StopA turn endsNoSound alerts, end-of-turn checks
SessionEndThe session closesNoSummaries, cleanup, session logs

Exit 0 lets the action through unchanged; on PreToolUse, exit 2 blocks it and feeds your script's stderr back to Claude as the reason. Every other exit code is treated as the hook itself erroring, not an intentional block — always exit 0 or 2 explicitly.

Recipes 1-3: formatting and lint hooks

These run on PostToolUse after Edit or Write. The file has already changed by the time the hook fires, so the job is cleanup, not prevention.

1. Auto-format on save

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write --ignore-unknown" }
        ]
      }
    ]
  }
}

Formats exactly the file Claude just touched — no full-repo Prettier pass, no waiting for a pre-commit hook to catch it later.

2. ESLint with a hard stop on new errors

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *.ts|*.tsx) npx eslint \"$f\" --max-warnings=0 || { echo 'Lint failed on '$f >&2; exit 2; };; esac" }
        ]
      }
    ]
  }
}

Exit 2 on PostToolUse can't undo the edit, but it does stop the turn from quietly moving on — Claude sees the lint error and fixes it before touching the next file.

3. Auto-run the matching test file

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "f=$(jq -r '.tool_input.file_path'); t=\"${f%.*}.test.${f##*.}\"; [ -f \"$t\" ] && npx vitest run \"$t\" --reporter=dot" }
        ]
      }
    ]
  }
}

Only fires when a sibling *.test.* file already exists, so new files without tests yet don't slow down every edit.

Recipes 4-6: safety and guardrail hooks

PreToolUse on Bash is the one spot where exit 2 means the command never ran at all — these three gate instead of warn.

4. Block secrets from being committed

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE '^git commit' && git diff --cached | grep -qE 'AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{20,}|-----BEGIN (RSA|OPENSSH) PRIVATE KEY-----' && { echo 'Blocked: staged diff looks like it contains a secret' >&2; exit 2; } || exit 0" }
        ]
      }
    ]
  }
}

Scans the staged diff for common key patterns (AWS access keys, OpenAI-shaped secret keys, private key headers) right before the commit runs, not after it's already in history.

5. Block destructive deletes and force-pushes to main

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE 'rm\\s+-rf\\s+(/|\\*|~)|push .*--force.*\\b(main|master)\\b' && { echo 'Blocked: destructive command pattern' >&2; exit 2; } || exit 0" }
        ]
      }
    ]
  }
}

One grep, two patterns — covers the two most common "oh no" bash commands a model can type in a single hook instead of two.

6. Require confirmation before npm publish or terraform apply

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE 'npm publish|terraform apply' && [ \"$CLAUDE_HOOK_CONFIRMED\" != \"1\" ] && { echo 'Blocked: run with CLAUDE_HOOK_CONFIRMED=1 to confirm a release/apply command' >&2; exit 2; } || exit 0" }
        ]
      }
    ]
  }
}

Blocks by default and requires you to set an env var before the session to let a release command through — a speed bump for the two commands that are hardest to undo.

Recipes 7-9: notification and automation hooks

Session-level events have no tool_input to inspect — these exist to get your attention, not to gate anything.

7. Desktop notification when Claude is waiting on you

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude is waiting for input\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}

macOS-only; swap osascript for notify-send on Linux or a powershell -Command "[System.Windows.Forms.MessageBox]"-style toast on Windows.

8. Heads-up before a long build or deploy starts

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE 'npm run build|docker build|terraform apply' && osascript -e 'display notification \"Long-running command starting\" with title \"Claude Code\"'; exit 0" }
        ]
      }
    ]
  }
}

Always exits 0 — purely informational, so the build still runs even if the notification fails.

9. Sound alert when a long-running turn finishes

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &" }
        ]
      }
    ]
  }
}

The trailing & matters — without it, the hook blocks the turn from actually ending until the sound finishes playing.

Recipes 10-12: testing and CI hooks

10. Block commits when the test suite is red

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE '^git commit' && { npm test --silent || { echo 'Blocked: test suite is failing' >&2; exit 2; }; } || exit 0" }
        ]
      }
    ]
  }
}

Every git commit runs the full suite first. On a solo project this is usually fast enough to be worth the wait; if your suite is slow, scope the grep to only run on commits touching src/.

11. Require Conventional Commits format

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); if echo \"$cmd\" | grep -qE \"^git commit\"; then msg=$(echo \"$cmd\" | grep -oE \"-m ['\\\"].*['\\\"]\"); echo \"$msg\" | grep -qE \"(feat|fix|chore|docs|refactor|test)(\\(.+\\))?:\" || { echo 'Blocked: commit message must follow Conventional Commits' >&2; exit 2; }; fi; exit 0" }
        ]
      }
    ]
  }
}

Keeps commit history parseable by changelog tooling without you having to remind the model every session.

12. Block gh pr create with an empty description

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE '^gh pr create' && ! echo \"$cmd\" | grep -qE -- '--body|--body-file' && { echo 'Blocked: gh pr create needs --body or --body-file' >&2; exit 2; } || exit 0" }
        ]
      }
    ]
  }
}

Stops a PR from shipping with the CLI's default placeholder body, which is the easiest thing to forget mid-flow.

Copy-paste settings.json template

Merge this into the top-level hooks key of .claude/settings.json. If you already have hooks configured, merge arrays per event instead of overwriting the file — don't just paste this block over an existing hooks key.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE '^git commit' && git diff --cached | grep -qE 'AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9]{20,}|-----BEGIN (RSA|OPENSSH) PRIVATE KEY-----' && { echo 'Blocked: staged diff looks like it contains a secret' >&2; exit 2; } || exit 0" },
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE 'rm\\s+-rf\\s+(/|\\*|~)|push .*--force.*\\b(main|master)\\b' && { echo 'Blocked: destructive command pattern' >&2; exit 2; } || exit 0" },
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE 'npm run build|docker build|terraform apply' && osascript -e 'display notification \"Long-running command starting\" with title \"Claude Code\"'; exit 0" },
          { "type": "command", "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -qE '^git commit' && { npm test --silent || { echo 'Blocked: test suite is failing' >&2; exit 2; }; } || exit 0" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write --ignore-unknown" }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude is waiting for input\" with title \"Claude Code\"'" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &" }
        ]
      }
    ]
  }
}

This bundles one recipe from each of the four categories above (secrets guard, build notification, test gate, formatter, idle alert, stop sound) as a reasonable solo-founder default — swap in the other six recipes individually as you need them.

AgenticKit ships these pre-configured

Writing and testing 12 of these by hand, including getting the jq piping and exit codes right on the first try, is a wasted afternoon. AgenticKit's security-auditor and devops-engineer agents ship with hook templates for the secrets, destructive-command, and commit-guardrail categories pre-wired, and the hooks builder tool generates the JSON for any recipe above — pick the event and matcher, get the snippet.

FAQ

How is this different from the other hooks posts on this site? Claude Code Hooks Examples explains the event model and exit-code mechanics in depth with 15 examples organized by event type; 20 Claude Code Hooks Examples That Actually Ship in Production ranks hooks by ROI. This post is organized by job — format, guard, notify, test — so you can jump straight to the category matching what you're trying to automate, with fewer words per recipe.

Can I run more than one hook per event? Yes — each event key takes an array of matcher objects, and each matcher object's hooks array can hold multiple commands, which all run for a matching tool call. The settings.json template above stacks four PreToolUse commands under one Bash matcher.

Do PostToolUse hooks slow down every edit? Yes, Claude Code waits for the hook process to exit before continuing, so keep PostToolUse commands fast — a Prettier pass on one file, not a full build. Scope the matcher narrowly (Edit|Write, not .*) so hooks only run on calls they actually apply to.

What happens if a hook script itself crashes? Any exit code other than 0 or 2 — including 1, 127 for "command not found," or an unhandled set -e failure — is treated as the hook erroring, not as an intentional block. Claude Code surfaces that the hook failed, which reads differently than "this action is disallowed," so test each script's exit path before relying on it.

Should these live in the repo or in my global Claude settings? Project-specific guardrails (lint rules, test commands, branch names) belong in the repo's .claude/settings.json so every contributor gets them. Personal preferences like desktop notifications or sound alerts usually belong in your user-level settings instead, so they don't force a notification sound on a teammate who clones the repo.

Is there a Cursor equivalent? Cursor hooks live in .cursor/hooks.json with a different event vocabulary (beforeShellExecution, afterFileEdit instead of PreToolUse/PostToolUse), so none of the JSON above is portable as-is — port the intent, not the literal config. See Claude Code Hooks vs MCP Servers for when to reach for a hook versus an MCP server in either tool.

Related Tools & Agents

🛠️ Free Tool: hooks-builder🤖 Agent: security-auditor🤖 Agent: devops-engineer🤖 Agent: code-reviewer⚡ Command: /audit⚡ Command: /shipSkill: security-basicsSkill: project-conventions

Build your hooks.json visually

Pick an event and a preset, then download a hooks file instead of hand-writing the JSON.

Open the hooks builder →