Controls the sound that plays when an agent turn ends. All the decision logic lives in the CLI, so this skill only has one job: translate a request into the right command. Never edit the state files directly — always go through the CLI.
First run
If notifysound was installed with skills add, only the skill files are in
place; the hooks are not. Skill managers deliberately do not edit home
configuration, so hook installation stays an explicit act. Run this once:
notifysound install
That installs the Claude Code Stop hook and the Codex CLI notify hook, and registers the 12 built-in sounds.
Command mapping
| User request | Command |
|---|---|
| "mute the sound" / "turn off the notification sound" | notifysound off |
| "turn the sound on" / "turn on the notification sound" | notifysound on |
| "silence codex only" / "quiet only codex" | notifysound off --host codex |
| "mute claude only" / "turn off only claude" | notifysound off --host claude |
| "put codex back to default" / "restore codex settings to default" | notifysound reset --host codex |
| "what is the sound state" / "how is the notification sound state now" | notifysound status |
| "what sounds are registered" / "what notification sounds are registered" | notifysound list |
| "register this file as the sound" / "register this file as the notification sound" | notifysound add <name> <file> |
| "switch to " / "change the notification sound to <name>" | notifysound use <name> |
| "let me hear it" / "let me hear the notification sound" | notifysound test |
| "delete the sound" / "delete the notification sound <name>" | notifysound remove <name> |
| "reinstall the hooks" / "reinstall the notification sound hooks" | notifysound install |
| "remove notifysound" / "remove the notification sound feature" | notifysound uninstall |
Rules
- If the user gives a file but no name, propose the filename (without its extension) as the default name and confirm before registering.
- If
addis rejected for a duplicate name, do not silently add--force— ask whether to overwrite. - If
removeis rejected because the sound is currently in use, ask which sound to switch to first. - After changing state, show the output of
notifysound status. removerefuses built-in sounds. They are install assets and would come back on the next install, so removal would be meaningless. Offeruseinstead.statusreports more than on/off and the current sound: it also reports installation health — whether each of Claude and Codex actually has a signed hook (installed/not installed), whether the target file exists at all (n/a, e.g. on a machine that does not use Codex), whether the player path is a dangling symlink (ok/broken), and whether each harness skill directory is linked. It is read-only. For any "I hear no sound" request, runnotifysound statusfirst.- Never edit
~/.claude/settings.json,~/.codex/hooks/notify.sh, or~/.claude/notifysound/config.jsonby hand. Use these CLI commands only. uninstalldoes not restore a previously existing sound hook. It strips the# notifysoundsignature and leaves no hook behind. That is intended. If the user expects "put my old sound back", say so first.addcopies the file, it does not reference it. The source is copied into~/.claude/notifysound/sounds/, so moving or deleting the original afterwards does not affect playback.
Layout
- State:
~/.claude/notifysound/config.json— globalenabled, per-host overrides (nullmeans "follow the global switch"), the currentsound, and the registered sound map. - User sounds:
~/.claude/notifysound/sounds/ - Built-in sounds: inside the install tree, registered on
install - Player:
notifysound-play.sh <host>— the single entry point the hooks call. It exits 0 on every path and writes nothing to stdout, so a sound problem can never break an agent turn. - CLI:
~/.local/bin/notifysound - Hooks: the
Stoparray in Claude Code'ssettings.json, and theagent-turn-completebranch in~/.codex/hooks/notify.sh. Both carry the# notifysoundsignature comment.
macOS only (depends on afplay). Supported extensions: mp3 wav aiff m4a aac.
Sound names accept [A-Za-z0-9_-] only.
Exit codes: 0 success, 1 user error, 2 environment error.