Notifysound

notifysound

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

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 add is rejected for a duplicate name, do not silently add --force — ask whether to overwrite.
• If remove is rejected because the sound is currently in use, ask which sound to switch to first.
• After changing state, show the output of notifysound status.
• remove refuses built-in sounds. They are install assets and would come back on the next install, so removal would be meaningless. Offer use instead.
• status reports 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, run notifysound status first.
• If install reports that the Codex hook still holds a pre-2.2 layout, do NOT edit notify.sh by hand to work around it. Tell the user what migrate does — it is the only command that decides where things sit in their script, it backs the file up first, and it is opt-in for that reason — and let them decide. Then run notifysound install.
• Never edit ~/.claude/settings.json, ~/.codex/hooks/notify.sh, or ~/.claude/notifysound/config.json by hand. Use these CLI commands only.
• uninstall does not restore a previously existing sound hook. It strips the # notifysound signature and leaves no hook behind. That is intended. If the user expects "put my old sound back", say so first.
• add copies 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 — global enabled, per-host overrides (null means "follow the global switch"), the current sound, 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: one entry in the Stop array of Claude Code's settings.json, and ONE line in ~/.codex/hooks/notify.sh — immediately after the shebang — which sources our own codex-hook.sh. Both carry the # notifysound signature. All of the Codex-side logic lives in our file, not in theirs, and install/uninstall only ever touch that single line at that single position.

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, 3 the Codex hook is in a pre-2.2 layout and notifysound migrate is needed first.