Play a sound when Codex finishes a prompt / task

[khryniewiecki]

Sound when Codex finishes

Summary
Please add an optional, clearly audible completion sound that plays when Codex finishes executing a prompt/task (useful when prompts run longer and the user switches focus).

Why
Helps when Codex works in background and I’m in another window/tab.
Terminal bell \a is too short/quiet and easy to miss.

Use case / Motivation
Most of my prompts take Codex quite a long time to execute — often more than a minute. It’s frustrating that I have to sit and stare at the screen just to know when it’s done. Since I work remotely, I could easily use that waiting time to do something else, as long as Codex informs me when it finishes.

Yes, I can (and already did) hack together my own workaround, but it would be much nicer if this were a built-in feature of the extension. For example, after finishing a prompt Codex could simply play a clear sound notification.

Environment
VSC

Extras
I would be cool if it plays: https://youtu.be/CduA0TULnow?list=RDCduA0TULnow&t=58

Are you interested in implementing this feature?

No response

Additional information

No response

[ropl-btc]

you can already do that by setting up a notification hook for it in your .codex config.toml.

just add this to your config.toml
notify = ["python3", "~/.codex/notify.py"]

and setup a notify.py file

#!/usr/bin/env python3
"""
Minimal notifier for Codex "notify" hook.
Plays a short sound when an agent turn completes.

Usage: Codex runs this script with a single JSON argument.
"""

import json
import os
import subprocess
import sys


def main() -> int:
    if len(sys.argv) != 2:
        return 0

    try:
        event = json.loads(sys.argv[1])
    except Exception:
        event = {}

    if event.get("type") != "agent-turn-complete":
        return 0

    # Prefer a built-in macOS sound if available; fall back to TTS.
    sound_path = "/System/Library/Sounds/Glass.aiff"
    try:
        if os.path.exists(sound_path):
            subprocess.Popen(["afplay", sound_path])
        else:
            subprocess.Popen(["say", "Codex turn complete"])  # best-effort fallback
    except Exception:
        pass

    return 0


if __name__ == "__main__":
    raise SystemExit(main())

[markgrover]

I had to a make a few tweaks (iterm2 on macOS):

• Relative path didn't work for me in my ~/.codex/config.toml, I had to use absolute path to my home dir

notify = ["python3", "/Users/YOUR_USER_NAME/.codex/notify.py"]

• Minor change to notify.py to use the terminal bell instead:

#!/usr/bin/env python3
"""
Minimal notifier for Codex "notify" hook.
Plays a short sound when an agent turn completes.

Usage: Codex runs this script with a single JSON argument.
"""

import sys
import json

def main():
    if len(sys.argv) != 2:
        return 0

    try:
        event = json.loads(sys.argv[1])
    except Exception:
        return 0

    if event.get("type") != "agent-turn-complete":
        return 0

    # Print BEL character -> terminal bell
    sys.stdout.write("\a")
    sys.stdout.flush()
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

• To test once it's all set up run:
  python3 ~/.codex/notify.py '{"type":"agent-turn-complete"}'

[samlouiscohen]

Love this ask. I implemented a cross-platform MVP that’s opt-in and uses system sounds (no bundled assets).

Proposal

• notifications.sound = true|false (default false)
• notifications.only_on_long_runs_ms = 0
• notifications.success_tone = "default" / notifications.error_tone = "default"
  • Maps to OS-appropriate system sounds:
    • macOS → Hero (success), Basso (error)
    • Windows → SystemSounds.Asterisk (success), SystemSounds.Hand (error)
    • Linux → canberra id complete (success), dialog-error (error)
• Fallback: terminal bell (\a) if no backend available
• Fires only on final agent-turn-complete

Why

• Improves the UX for long-running tasks without requiring custom notify hook scripts
• Only system sounds → zero new binary assets
• Safe defaults, fully optional, and configurable via ~/.codex/config.toml
• Increasingly relevant as model time horizons grow longer — Codex runs already take tens of minutes in some cases. An audible success/failure cue makes it possible to safely multitask while waiting.

Example Config

[notifications]
sound = true
only_on_long_runs_ms = 10000
success_tone = "default"
error_tone = "default"

Opened a PR to implement this: #4329

It adds:

• notifications.sound (default off)
• notifications.only_on_long_runs_ms
• success_tone / error_tone with sensible per-OS defaults
• Fallback to terminal bell

Cross-platform mappings:

• macOS → Hero (success), Basso (error)
• Windows → SystemSounds.Asterisk / Hand
• Linux → canberra complete / dialog-error

[atreeon]

Would this proposal result in the cli playing a sound if the task pauses asking for approval?

[jsh9]

Hi @samlouiscohen , does your code change work for the VS Code extension as well? Or only the CLI version of Codex?

[budingkak12]

我尝试了很多次，都通知失败，最后，我把notify = ["python3", "/Users/wang/.codex/notify.py"]
放到disable_response_storage = true的后面一行 成功了，（我之前一直放在
trust_level = "trusted"
后面，导致一直失败，很神奇）

[budingkak12]

"I tried many times, but the notification failed every time. Finally, I moved the line notify = ["python3", "/Users/wang/.codex/notify.py"] right after disable_response_storage = true, and it worked! (It's strange because it kept failing when I had it after trust_level = "trusted".)"

[rijieli]

For macOS users, I found a simple way to play sounds or notifications using the Shortcuts app, which has higher permissions. I configured the TOML file accordingly.

notify = ["zsh", "/Users/roger/.codex/notify.sh"]

[tui]
notifications = true

#!/bin/zsh
/usr/bin/shortcuts run "Codex Done"

[jsh9]

The following worked for me on macOS, simple and easy to maintain, without the hassle of creating a Python script (notify.py) or a Shortcut.

In ~/.codex/config.toml, add this line:

model = "gpt-5-codex"
model_reasoning_effort = "low"
+ notify = ["bash", "-lc", "afplay /System/Library/Sounds/Bottle.aiff"]

/System/Library/Sounds has many different ringtones for you to choose. You don't have to use my choice.

/System/Library/Sounds
├── Basso.aiff
├── Blow.aiff
├── Bottle.aiff
├── Frog.aiff
├── Funk.aiff
├── Glass.aiff
├── Hero.aiff
├── Morse.aiff
├── Ping.aiff
├── Pop.aiff
├── Purr.aiff
├── Sosumi.aiff
├── Submarine.aiff
└── Tink.aiff

(Inspired by #4998 (comment))