How to use Claude Code hooks

Issue #1032

Claude Code runs fast. Sometimes too fast — you walk away, come back, and have no idea if it finished or is still working. Hooks solve this.

A hook is a shell command that runs automatically at specific points in Claude’s lifecycle. When Claude stops, a command runs. When Claude needs your attention, another command runs. You configure them once in settings.json and forget about them.

Hook Events

Claude Code has 26+ hook events covering the full session lifecycle. A few stand out as the most useful day to day.

• Stop fires when Claude finishes responding. This is the one to use for “task done” alerts.
• Notification fires when Claude needs you — a permission prompt, a question, anything requiring input.
• PreToolUse fires before any tool runs and can block it, making it useful for safety checks or logging.
• PostToolUse fires after a tool succeeds, which is handy for auto-formatting files after Claude edits them.
• SessionStart fires once when a session begins, good for loading environment setup.

Setting Up Sound Alerts

The simplest hook plays a sound. On macOS, afplay plays any audio file from the command line. Pair it with Stop and Notification, and you get audio feedback without watching the screen.

"hooks": {
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "afplay /System/Library/Sounds/Hero.aiff"
        }
      ]
    }
  ],
  "Notification": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "afplay /System/Library/Sounds/Submarine.aiff"
        }
      ]
    }
  ]
}

This config goes in ~/.claude/settings.json to apply globally across all projects.

Choosing Your Sound

macOS ships with 14 system sounds in /System/Library/Sounds:

Basso, Blow, Bottle, Frog, Funk, Glass, Hero,
Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink

Pick different sounds for different events. Hero for task complete, Submarine for attention needed. Or use Ping if you prefer something subtle, Funk if you don’t.

You can also point afplay at any .aiff or .mp3 file on your system.

How ralph Uses the Stop Hook

ralph is an autonomous coding framework that loops through user stories from a requirements document. It spawns fresh Claude instances in sequence, each tackling one story at a time.

Ralph uses the Stop hook as its restart trigger. When Claude finishes a story and stops, the hook fires — which kicks off the next iteration. This turns a one-shot AI session into a continuous autonomous loop. The hook is the glue between cycles.

Going Further with peon-ping

If system sounds aren’t enough, peon-ping takes notifications much further. It delivers voice lines and on-screen overlays when Claude completes tasks or needs attention — including character voices from Warcraft, StarCraft, Portal, and Zelda.

It registers itself as a Claude Code hook and monitors task lifecycle events. You get a /peon-ping-toggle command inside Claude Code to turn it on or off.

Hooks are just shell commands. The ceiling for what you can trigger is as high as your shell scripts will take you.