claude-sound-hooks

Adds audio notifications to Claude Code — plays a sound when Claude finishes a task (Stop) and when it needs your attention (Notification).

Usage

npx claude-sound-hooks

That's it. The tool will:

1. Copy the bundled sound files to ~/.claude/hooks/claude-sound-hooks/
2. Detect your OS and available audio player
3. Write the hooks into ~/.claude/settings.json

Then restart Claude Code or open /hooks to reload settings.

Platform support

| OS | Player used | |----|-------------| | Linux | paplay → pw-play → aplay (first found) | | macOS | afplay | | Windows | PowerShell Media.SoundPlayer |

Sounds

| Hook | Sound | |------|-------| | Notification | dialog-warning.oga | | Stop | complete.oga |

Sourced from the freedesktop sound theme.

What gets written

~/.claude/settings.json — only the Notification and Stop hook entries are touched; everything else (permissions, other hooks, etc.) is preserved.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "paplay '~/.claude/hooks/claude-sound-hooks/dialog-warning.oga' >/dev/null 2>&1 &" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "paplay '~/.claude/hooks/claude-sound-hooks/complete.oga' >/dev/null 2>&1 &" }]
      }
    ]
  }
}

Development

npm install
npm run build   # compiles src/index.ts → dist/index.js
npm run dev     # run directly with tsx (no build step)