From Scratch: Build Automated Claude Code Workflows with Hooks

You ask Claude Code to write features, supplement tests, format files, and then commit. It writes the features, adds most of the tests, formats two files, but misses one. Then it tells you, "All done." You check: nothing committed, formatting not fully aligned. These issues shouldn't require your post-hoc checks. In Claude Code, they can all be configured as automated workflows. That's why hooks exist.

Claude Code hooks are shell commands automatically executed at fixed nodes in Claude's lifecycle. You don't need to instruct Claude; the hook runs on its own. Claude may not run a formatter. A hook attached to PostToolUse can run Prettier after every file edit. Claude may forget to notify you. A hook on Notification can pop up whenever Claude needs your input. Hooks pull behavior out of Claude's judgment and into your project rules—code quality, notifications, security checks. These crucial tasks should live in hooks, not prompts. GitButler's guide: start with three—PostToolUse auto-formatting, PreToolUse interception of dangerous commands, Stop desktop notification—to get the widest coverage with the least effort.

Claude Code has over 20 lifecycle events, but you really use these five: PostToolUse (triggered after Claude uses a tool—auto-format, lint, log changes); PreToolUse (triggered before tool use, can block—protect sensitive files, prevent dangerous commands); Notification (triggered when Claude needs your attention—desktop alerts so you don't stare at the terminal); Stop (triggered when Claude finishes a reply—run tests, CI, auto-commit); SessionStart (triggered on session start or resume—reload context after compaction, load environment reminders). Skip the rest for now; start with these five.

Beyond the standard shell command hook ("type": "command"), there are three more: Prompt Hook (type: prompt) passes hook input to a Claude model (default Haiku) for yes/no judgment, useful when you need model understanding—e.g., checking if all tasks are complete before Claude stops:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

Better than regex. Agent Hook (type: agent) spawns a sub-agent that can read files, search code, run tools for up to 50 turns—useful when you need to cross-reference actual code state, e.g., verifying tests pass before stopping. HTTP Hook (type: http) POSTs event data to a URL, no shell required—good for team audit logs, shared notification services, webhook integrations. In most cases, "type": "command" is sufficient.

Hook configs go in one of three locations:

~/.claude/settings.json  all projects
.claude/settings.json  current project (committed, shared with team)
.claude/settings.local.json  current project, not committed

The structure is the same:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName|OtherTool",
        "hooks": [
          {
            "type": "command",
            "command": "your shell command here"
          }
        ]
      }
    ]
  }
}

Matcher is a regex that filters triggers. In PostToolUse and PreToolUse, match tool names: "Edit|Write" triggers after file edits, "Bash" after shell commands, "mcp__github_.*" after any GitHub MCP tool call. The easiest way is the /hooks interactive menu—type /hooks in Claude Code, select event, set matcher, enter command, no hand-editing JSON. Takes effect immediately.

1. Notification when Claude needs you: Stop staring at the terminal. Every time Claude waits for you—permission confirmations, idle waits, any intervention—pop this up:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Place in ~/.claude/settings.json for global effect.

2. Auto-format files Claude touches: After every Edit or Write, run Prettier. Eliminate formatting inconsistencies from Claude's incremental edits once and for all:

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

Requires jq for JSON parsing (install via brew install jq on macOS). Put in project's .claude/settings.json and commit as a team standard.

3. Prevent Claude from touching protected files: Block .env, package-lock.json, .git/. Claude will get feedback explaining why:

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

Make executable with chmod +x .claude/hooks/protect-files.sh, then register:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

4. Refill context after compaction: When the context window fills and Claude summarizes (compaction), important details can be lost. This hook triggers after each compaction to remind Claude of the essentials:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

You can replace echo with dynamic commands like git log --oneline -5 or cat .claude/sprint-context.md to load a dedicated context file.

5. Enforce git commit message conventions: Claude sometimes writes commit messages with the wrong type prefix, sentence case, or a trailing period. This hook intercepts before the commit lands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Look at tool_input.command. If it does NOT start with 'git commit', return {\"ok\": true}. If it is a git commit command, extract the commit message and check only the FIRST LINE (subject line) — ignore any body lines after the first newline. Check: (1) format is 'type: Capitalized description' where type is one of feat/fix/refactor/docs/chore/perf/revert, (2) description starts with a capital letter, (3) no trailing period, (4) no 'Co-Authored-By' trailer anywhere in the command. Return {\"ok\": false, \"reason\": \"[specific issue. Corrected subject line: type: Description]\"} if any check fails. Return {\"ok\": true} if all pass."
          }
        ]
      }
    ]
  }
}

This is a Prompt Hook—no shell script, no regex; let Haiku read the command, check against your rules, and return the result. Place in ~/.claude/settings.json for all projects.

Hook scripts communicate with Claude Code through three channels:

Stdout: added to Claude's context
  Used for SessionStart, UserPromptSubmit, etc.

Stderr: displayed to Claude when exit code 2 is used

Exit code: determines what happens next:

0 → continue
2 → block the current action
     stderr message is fed back to Claude
other → continue
     stderr is logged (viewable via Ctrl+O)

The real power of PreToolUse hooks lies in this exit code system: your script reads the operation Claude is about to perform, checks it against rules, and either allows it or returns a specific reason.

Step 1: Add a global notification hook. Open ~/.claude/settings.json and paste the macOS notification config above. Most practical, zero risk, purely additive—it doesn't block anything. Make Claude do something that triggers a permission confirmation to test the popup. Step 2: Add Prettier formatting to the current project. Open (or create) .claude/settings.json in your project root, add the PostToolUse formatting hook. Install jq if needed. Have Claude edit a file and confirm it's auto-formatted. Step 3: Open /hooks and explore. The interactive menu lists all events and descriptions. Think about what else in your workflow could be automated. The Stop event (run tests after Claude finishes) and PreToolUse (intercept specific patterns) are good next choices.

Without hooks, you have to follow up and check: was formatting run? were tests run? was the code committed? With hooks, these questions are answered. Formatting always runs, tests always run, notifications always pop up. They no longer depend on whether Claude remembers, understands, or complies—they become the default behavior of the project environment. Don't hang critical workflows on prompt constraints. Enforce crucial actions through environmental mechanisms, ensuring they execute reliably every run.