# Sound Hooks

> Configure macOS sound notifications for Claude Code hooks. Use this skill when the user wants to add sounds to Claude Code, play audio on task completion, get notified with a sound when Claude stops or asks a question, set up hook sounds, configure notification sounds, or add audio feedback to their Claude Code workflow. Also use when they mention "play a sound", "ding when done", "notify me", or "audio alerts" in the context of Claude Code settings.

- Skill: `ralphcrisostomo/sound-hooks` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ralphcrisostomo/sound-hooks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ralphcrisostomo/sound-hooks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ralphcrisostomo (https://skillmd.com/u/ralphcrisostomo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ralphcrisostomo/sound-hooks

---


# 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:

```json
"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:

```bash
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:

```json
"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.