ralphcrisostomo 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
/hooksor restart the session for new hooks to take effect (settings watcher caveat) - They can change sounds later by editing
~/.claude/settings.jsonor 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.