Codex Sound Notifications

Setup Sound Notifications

Install a reusable completion sound for Codex with the bundled scripts and bundled WAV assets. Prefer the installer script so the selected asset file and notify command stay in sync.

Prerequisites

• Run on macOS with afplay available.
• Bundled sounds live under assets/sounds/.
• Use a local sound zip only when importing a new sound pack into the skill.
• Expect write access to ~/.codex/config.toml.
• If importing a new sound pack, expect write access to assets/sounds/ inside the skill folder.

Workflow

1. Confirm the user wants a persistent Codex completion sound, not a one-off shell command.
2. Prefer an existing bundled sound under assets/sounds/.
3. Only if the requested WAV is not bundled, collect a local zip path and import sounds into assets/sounds/.
4. If the user asks to update the skill itself, prefer python3 scripts/manage_sound_notifications.py --check-update first, then --update.
5. Run python3 scripts/test_sound_notifications.py.
6. Prefer python3 scripts/manage_sound_notifications.py for interactive switching with preview and confirmation.
7. Run python3 scripts/setup_sound_notifications.py only for direct non-interactive installs.
8. If the user already has notify = [...] in ~/.codex/config.toml, let the installer wrap and forward the old command instead of overwriting it.
9. Validate on a temp config first when possible, then install to the real config.
10. --check-update and --update need network access; if the sandbox blocks GitHub or git fetch, request approval.

Defaults

• Default completion sound: celebration.wav.
• Softer alternative for the same archive family: notification.wav.
• Default event filter: agent-turn-complete.
• Bundled WAV files live under assets/sounds/.

Commands

python3 scripts/test_sound_notifications.py
python3 scripts/manage_sound_notifications.py
python3 scripts/manage_sound_notifications.py --list
python3 scripts/manage_sound_notifications.py --preview celebration.wav
python3 scripts/manage_sound_notifications.py --apply celebration.wav --yes
python3 scripts/manage_sound_notifications.py --check-update
python3 scripts/manage_sound_notifications.py --update
python3 scripts/setup_sound_notifications.py
python3 scripts/setup_sound_notifications.py --sound-file celebration.wav
python3 scripts/setup_sound_notifications.py --zip-path /path/to/SND03_industrial.zip --sound-file celebration.wav

Interactive Sound Command

• python3 scripts/manage_sound_notifications.py starts an interactive bundled-sound picker.
• The command lists all bundled WAV files, marks the current sound, previews the selected sound, and asks for confirmation before applying it.
• Use --list, --preview , or --apply --yes for non-interactive sound flows.
• Use --check-update to compare the local skill with upstream.
• Use --update to update the installed skill. Git checkouts use git fetch plus git pull --ff-only; non-git installs download the latest GitHub archive, overlay upstream files, and keep extra local files such as imported custom sounds.

What The Installer Changes

• Point Codex notify directly at the selected bundled WAV under assets/sounds/.
• Optionally import one WAV from a zip into assets/sounds/ when --zip-path is provided.
• Set Codex notify = [...] to the bundled notifier script.
• Preserve an existing notify command by forwarding the same JSON payload to it after local playback.

Notes

• Use Codex official docs as source of truth for config behavior: https://developers.openai.com/codex/config-reference and https://developers.openai.com/codex/config-advanced.
• Update checks for non-git installs use GitHub's REST commits and repository archive endpoints: https://docs.github.com/en/rest/commits/commits and https://docs.github.com/en/rest/repos/contents.
• Rely on afplay for playback; verify with command -v afplay or man afplay.
• The public docs define notify but do not fully document every JSON payload shape. The notifier script therefore accepts a few compatible event field names and a legacy after-agent payload shape.
• notify and tui.notifications are separate Codex mechanisms; this skill configures notify only.
• The notifier skips known internal bootstrap prompts such as hidden You are ... threads to avoid double sounds on a new session's first reply.
• Keep reusable sound assets in assets/sounds/; notify should point directly at the selected asset file.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zty42
• Source: zty42/codex-sound-notifications
• License: MIT

Install and usage instructions live in the source repository linked above.