Audio Notification Hooks: Know Which Session Finished

Summary

When running multiple Claude Code sessions in parallel, you need to know when each one finishes without constantly checking every terminal window. A Stop hook that plays a system sound via afplay lets you walk away and come back when you hear the chime. Simple config, high impact for multi-session workflows.

The Problem

Running 4-6 parallel Claude Code sessions means constant window-switching to check progress. You end up either:

1. Polling: Alt-tabbing through windows every 30 seconds, breaking your focus
2. Missing completions: A session finishes, sits idle for 10 minutes while you are focused elsewhere
3. Walking away blind: Leaving your desk with no idea whether sessions are done

Visual notifications (macOS alerts, menubar badges) get lost in the noise. You need something that interrupts ambient attention without requiring screen focus.

The Solution

Add a Stop hook to ~/.claude/settings.json that plays a system sound when Claude Code finishes a response:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Blow.aiff"
          }
        ]
      }
    ]
  }
}

How it works

1. Claude Code finishes processing (any session)
2. The Stop hook fires
3. afplay plays the system sound
4. You hear the chime from across the room and know a session is ready

Available macOS system sounds

Pick a sound that cuts through your environment:

Test them: afplay /System/Library/Sounds/Glass.aiff

Different sounds per session

If you want to distinguish which session finished, you can use project-level settings (.claude/settings.json in each project directory) with different sounds. Or use a script that incorporates the working directory:

#!/bin/bash
# ~/.claude/hooks/stop-sound.sh
# Play different sounds based on project directory
case "$PWD" in
  */octospark*) afplay /System/Library/Sounds/Hero.aiff ;;
  */knowledge-base*) afplay /System/Library/Sounds/Glass.aiff ;;
  *) afplay /System/Library/Sounds/Blow.aiff ;;
esac

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/stop-sound.sh"
          }
        ]
      }
    ]
  }
}

Linux alternative

Replace afplay with paplay or aplay:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga"
          }
        ]
      }
    ]
  }
}

Integration with Parallel Workflows

This hook becomes essential when combined with:

• YOLO mode: Sessions run autonomously, so you are not watching the terminal. The sound tells you when to check in.
• 4-6 parallel sessions: Without audio cues, you would need to visually poll every window.
• Walk-away workflows: Start a plan or implementation, leave the desk, return when you hear the sound.

The pattern: start work in a session, switch to the next window, hear the chime, cycle back and react. Audio becomes the scheduling signal for your attention across parallel agents.

Related

• Claude Code Hooks as Quality Gates – Hooks for automated verification (quality focus vs. notification focus)
• AI Workflow Notifications – Webhook-based notifications for CI/CD (remote) vs. audio (local)
• YOLO Mode Configuration – Autonomous execution that benefits from audio completion signals
• Parallel Agents for Monorepos – Multi-session workflows where audio cues matter most
• 24/7 Development Strategy – Overnight runs where audio signals task completion at wake-up

References

• Matt Van Horn – Every Claude Code Hack I Know (March 2026) – Original source for the afplay Stop hook pattern
• Credit: Myk Melez (original hook idea), Dan Shapiro (bypass permissions workflow)