Play notification sound when Claude Code Agent has finished working.

README.md

Claude Code has introduced a new feature called hooks which lets you run a script during different events. One of the event is Stop, which runs when the main Claude Code agent has finished responding.

We can make the use of this hook to play a notification sound.

You can download this notification sound (downloads automatically) from mixkit

Paste this JSON into .claude/settings.json, either project or global .claude folder. Make sure to update the path of the script.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/play-sound.sh"
          }
        ]
      }
    ]
  }
}

Here's a shell script which plays the sound play-sound.sh.

#!/bin/bash

SOUND_TYPE=$1
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

# Define sound files
COMPLETE_SOUND="./done.wav"
SOUND_FILE=$COMPLETE_SOUND

# Play sound based on OS
if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS
    afplay "$SOUND_FILE" 2>/dev/null &
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
    # Linux
    if command -v aplay &> /dev/null; then
        aplay "$SOUND_FILE" 2>/dev/null &
    elif command -v paplay &> /dev/null; then
        paplay "$SOUND_FILE" 2>/dev/null &
    fi
elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]] || [[ "$OSTYPE" == "win32" ]]; then
    # Windows
    powershell -c "(New-Object Media.SoundPlayer '$SOUND_FILE').PlaySync()" 2>/dev/null &
fi

Make sure to update the permission with chmod +x play-sound.sh.

---

That's it. Now whenver Claude is done, it would play a sound :)

Cheers 🥂

Like many of you, I got tired of babysitting the terminal waiting for Claude Code to finish. Claude Code runs in the terminal with zero feedback when it finishes, needs input, or hits an authorization wall. You either stare at the screen or keep context-switching back to check.

The solution: Claude Code Audio Hooks gives you distinct audio cues for 9 different events — task completion, authorization requests, subagent finishing, session start/end, tool execution, context compaction, and more. Each event has its own sound so you know what happened without looking.

Welcome to use 👉 https://github.com/ChanMeng666/claude-code-audio-hooks

Open source under MIT.

Would love your feedback!