soundsh

The CLI for installing alert sounds into Claude Code, Codex, and OpenCode.

Never miss when Claude finishes responding. Browse curated sounds, preview them instantly, and install with a single command.

Install a Sound

npx soundsh add soundsh/wololo

This downloads the audio file, configures a Claude Code hook, and plays a preview.

Tool Flags

| Flag | Description | | ---- | ----------- | | --codex | Install for Codex instead of Claude Code | | --opencode | Install for OpenCode instead of Claude Code |

Options

| Option | Description | | ---------------------- | ------------------------------------------------------ | | -g, --global | Install globally (~/.claude/settings.json) | | -p, --project | Install for current project (.claude/settings.json) | | -s, --stop | Trigger on response complete (Stop hook) | | -n, --notification | Trigger on notification (Notification hook) | | -t, --task-completed | Trigger on task completed (TaskCompleted hook) | | --ps, --prompt-submit| Trigger on prompt submitted (UserPromptSubmit hook) | | --hook <event> | Set hook event by name | | --scope <scope> | Set scope by name (global or project) |

Examples

# Fully non-interactive (no prompts)
npx soundsh add soundsh/wololo -g -s

# Install a notification sound globally
npx soundsh add soundsh/mgs-alert -g -n

# Install a task completed sound for this project
npx soundsh add soundsh/gta-mission-passed -p -t

# Install a prompt submit sound
npx soundsh add soundsh/mario-coin --ps

# Install for Codex
npx soundsh add soundsh/wololo --codex -g

# Install for OpenCode
npx soundsh add soundsh/wololo --opencode -g

# Interactive (prompts for scope and hook event)
npx soundsh add soundsh/zelda-chest

Installation Scope

| Scope | Flag | Location | Use Case | | ----------- | ---- | ---------------------------- | -------------------------- | | Global | -g | ~/.claude/settings.json | All projects on your machine | | Project | -p | .claude/settings.json | This project only |

If no flag is provided, you'll be prompted to choose.

Hook Events (Claude Code)

Each sound is bound to a Claude Code hook event that determines when it plays:

| Event | Flag | Description | | ------------------ | ----- | ----------------------------------------------- | | Stop | -s | When Claude finishes responding to your prompt | | Notification | -n | When Claude needs your attention | | TaskCompleted | -t | When a background task finishes | | UserPromptSubmit | --ps | When you send a message to Claude |

Installing a new sound on an event that already has a sound replaces it (no duplicates).

OpenCode Events

When using --opencode, you'll be prompted to select an event:

| Event | Description | | ------------------ | ----------------------------------------------- | | session.idle | When OpenCode finishes responding | | permission.asked | When OpenCode asks for permission | | session.error | When an error occurs |

Other Commands

| Command | Description | | -------------------------- | --------------------------------------------- | | npx soundsh find | Browse and preview sounds interactively | | npx soundsh list | List installed sounds | | npx soundsh remove [hook]| Remove an installed sound by hook | | npx soundsh preview <slug>| Preview a sound without installing | | npx soundsh theme <slug> | Install a sound theme | | npx soundsh themes | List available themes |

soundsh find

Interactive browser with live audio preview. Navigate with arrow keys, press Enter to install.

npx soundsh find
npx soundsh find --codex
npx soundsh find --opencode

  ▸ Wololo              soundsh         Multi-purpose
    AoE2 Horn            soundsh         Complete
    MGS Alert            soundsh         Notification
    Mario Coin           soundsh         Prompt

  ↑↓ Navigate  ⏎ Install  q Quit

soundsh list

Show all installed sounds grouped by tool and scope.

npx soundsh list

Claude Code — Global (~/.claude/settings.json):

  soundsh/wololo  (Stop)
  soundsh/mgs-alert  (Notification)

Codex — Global (~/.codex/config.toml):

  soundsh/wololo  (notify)

OpenCode — Global (~/.config/opencode/):

  soundsh/wololo  (session.idle)

soundsh remove

Remove a sound by hook name, or use --all to remove everything.

npx soundsh remove response           # Remove the response/Stop sound
npx soundsh remove notification       # Remove the notification sound
npx soundsh remove --all              # Remove all Claude Code sounds
npx soundsh remove --all -g           # Remove all global sounds only
npx soundsh remove --codex            # Remove Codex sound
npx soundsh remove --opencode         # Remove all OpenCode sounds

soundsh preview

Listen to a sound without installing it.

npx soundsh preview soundsh/zelda-chest

How It Works

Claude Code

Claude Code has a hooks system that runs shell commands on specific events. The CLI configures a hook that plays an audio file:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "# sounds.sh: soundsh/wololo\nafplay \"~/.claude/sounds/soundsh--wololo.mp3\""
          }
        ]
      }
    ]
  }
}

Codex

Codex uses a notify command in ~/.codex/config.toml:

notify = ["bash", "-c", "# sounds.sh: soundsh/wololo\nafplay ~/.claude/sounds/soundsh--wololo.mp3"]

OpenCode

The CLI generates a plugin file at ~/.config/opencode/plugins/soundsh.js (global) or .opencode/plugins/soundsh.js (project). OpenCode auto-discovers plugins in these directories. The plugin listens to OpenCode events and plays the configured sound.

Audio files are stored in ~/.claude/sounds/. The CLI manages hooks using a # sounds.sh: marker comment and also migrates legacy audio-only hooks on the same event so old sound commands do not keep firing after an install.

Platform Support

| Platform | Audio Player | Notes | | -------- | ------------ | ----- | | macOS | afplay (built-in) | | | Linux | paplay, aplay, or mpv | Install pulseaudio-utils for paplay | | Windows | PowerShell SoundPlayer | MP3s auto-converted to WAV via ffmpeg |

Browse Sounds

Discover sounds at sounds.sh

License

MIT