Sound Hooks Setup

Add macOS system sounds to Claude Code hook events so you get audio feedback when things happen — tasks finish, Claude stops to ask you something, etc.

How It Works

macOS ships with system sounds at /System/Library/Sounds/. This skill adds hooks to ~/.claude/settings.json that play these sounds via afplay (a built-in macOS command-line audio player). The & suffix makes playback non-blocking so it never slows Claude down.

Available Sounds

These are the built-in macOS system sounds (all .aiff files in /System/Library/Sounds/):

Sound	Character
Glass	Clean, bright chime — great for "something finished"
Blow	Soft puff — good for "needs your attention"
Ping	Classic notification ping
Pop	Quick, subtle pop
Hero	Triumphant, positive
Funk	Error-ish, something went wrong
Basso	Deep, serious — good for errors or warnings
Purr	Gentle vibration feel
Tink	Tiny, minimal tap
Bottle	Hollow pop
Frog	Quirky ribbit
Morse	Dot-dash beep
Sosumi	Classic Mac alert
Submarine	Sonar ping

Default Sound Map

Unless the user requests specific sounds, use these defaults:

Hook Event	Sound	Why
TaskCompleted	Glass	Clean completion chime
Stop	Blow	Soft "hey, I need you" nudge

Supported Hook Events

Any hook event can have a sound. The most useful ones for audio alerts:

Event	When it fires
TaskCompleted	A background task finishes
Stop	Claude finishes its turn (asks a question, completes work)
Notification	A notification is sent
SubagentStop	A subagent finishes
SessionStart	A new session begins

Setup Steps

1. Read the existing settings

Always read ~/.claude/settings.json first. Never overwrite existing settings.

2. Check for existing hooks

If hooks already exists, merge into it. If a hook event already has a sound configured, ask the user before replacing it.

3. Add sound hooks

Each sound hook follows this structure:

"EventName": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "afplay /System/Library/Sounds/SoundName.aiff &",
        "timeout": 5
      }
    ]
  }
]

The & is important — it backgrounds the audio so it doesn't block Claude.

4. Validate

After writing, validate with:

jq -e '.hooks' ~/.claude/settings.json

5. Inform the user

Tell the user:

• Which sounds were mapped to which events
• That they may need to open /hooks or restart the session for new hooks to take effect (settings watcher caveat)
• They can change sounds later by editing ~/.claude/settings.json or asking you to swap them

Customization

If the user wants a specific sound for a specific event, just swap the filename. For example, to use Hero instead of Glass for task completion:

"command": "afplay /System/Library/Sounds/Hero.aiff &"

If the user wants to use a custom sound file (not a system sound), they can provide an absolute path to any .aiff, .mp3, or .wav file — afplay handles all of these.

Platform Note

This skill is macOS-only. afplay and /System/Library/Sounds/ are macOS-specific. On Linux, an equivalent approach would use paplay or aplay, but the sound file paths differ entirely.