Hooks Setup: From Zero to Production

Claude Code can run shell commands, edit files, and interact with git on your behalf. That power is useful until it touches something it should not. Hooks are your guardrails: shell scripts that fire automatically before or after Claude acts, blocking dangerous operations and logging everything silently in the background.

The 6 hooks

Activate all hooks: settings.json

Add this configuration to ~/.claude/settings.json to wire up all six hooks. Each entry maps a hook lifecycle event to the script that handles it. Once saved, hooks activate immediately on the next Claude Code session.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/bash-safety.sh" }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/file-protection.sh" }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/file-backup.sh" }
        ]
      },
      {
        "matcher": "WebSearch",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/search-year.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/file-logger.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/stop-notify.sh" }
        ]
      }
    ]
  }
}

After saving, run: chmod +x ~/.claude/hooks/*.sh

Hook lifecycle

Understanding when each hook fires helps you choose the right event for your use case. PreToolUse hooks can block an action by returning exit code 2. PostToolUse hooks run after the fact and are observation-only. The Stop hook fires once at the end of every turn.

Claude receives your message
        │
        ▼
┌───────────────────────┐
│   PreToolUse hooks    │  ← bash-safety, file-protection, file-backup, search-year
│   (can block action)  │
└──────────┬────────────┘
           │  approved
           ▼
┌───────────────────────┐
│   Tool executes       │  Bash / Edit / Write / WebSearch / …
└──────────┬────────────┘
           │  done
           ▼
┌───────────────────────┐
│   PostToolUse hooks   │  ← file-logger
│   (observe only)      │
└──────────┬────────────┘
           │
           ▼
     (repeat per tool call)
           │
           ▼
┌───────────────────────┐
│   Stop hook           │  ← stop-notify  (fires once at end of turn)
└───────────────────────┘

Debugging cheatsheet