# Claude Code Hooks Cookbook: 12 Automations Solo Founders Ship

> 12 copy-paste Claude Code hooks grouped by job — formatting, safety guardrails, notifications, testing/CI — plus a cheat table and one merged settings.json template, for solo founders who want the recipe, not the reference manual.

Canonical: https://www.agentickit.co/blog/claude-code-hooks-cookbook-12-automations
Last updated: 2026-11-17

**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](/blog/claude-code-hooks-examples) 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

| Event | Fires when | Can block? | Typical use |
|---|---|---|---|
| `PreToolUse` | Before a tool call runs | Yes — exit `2` | Guardrails: secrets, destructive commands, protected branches |
| `PostToolUse` | After a tool call completes | No (turn-level only) | Formatting, linting, auto-test, logging |
| `Notification` | Claude is waiting on input | No | Desktop/sound alerts |
| `Stop` | A turn ends | No | Sound alerts, end-of-turn checks |
| `SessionEnd` | The session closes | No | Summaries, 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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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`**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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.

```json
{
  "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](/tools/hooks-builder) 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](/blog/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](/blog/20-claude-code-hooks-examples-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](/compare/claude-code-hooks-vs-mcp-servers) for when to reach for a hook versus an MCP server in either tool.


## Related
- [hooks-builder](https://www.agentickit.co/tools/hooks-builder)
- [security-auditor](https://www.agentickit.co/agents/security-auditor)
- [devops-engineer](https://www.agentickit.co/agents/devops-engineer)
- [code-reviewer](https://www.agentickit.co/agents/code-reviewer)
- [security-basics](https://www.agentickit.co/skills/security-basics)
- [project-conventions](https://www.agentickit.co/skills/project-conventions)
- [/audit](https://www.agentickit.co/commands/audit)
- [/ship](https://www.agentickit.co/commands/ship)
