Codex CLI Notifications

macOS desktop notifications for completed OpenAI Codex CLI turns.

This installs a global Codex notify hook in ~/.codex/config.toml, so it works from any repository. Codex invokes notify for supported notification events, currently agent-turn-complete, and passes a JSON payload containing fields such as cwd, thread-id, turn-id, input-messages, and last-assistant-message.

By default, the notifier filters to terminal-oriented Codex CLI sessions. It suppresses Codex app-server invocations, Codex app workspaces under ~/Documents/Codex, and any invocation that does not inherit terminal session environment variables.

It is not tied to VS Code. The hook works from Terminal.app, iTerm2, VS Code, Cursor, WezTerm, and other terminals because the notification is emitted at the OS level.

Support Status

This project is currently supported and manually tested on macOS only.

The notifier script includes experimental Linux (notify-send) and Windows (PowerShell toast) branches, and the automated tests exercise those branches with fake notification binaries. They are not yet manually verified as supported installs.

On non-macOS systems, the installer exits by default. To experiment anyway:

CODEX_NOTIFY_ALLOW_UNSUPPORTED=1 ./install.sh

Install

Install directly:

curl -fsSL https://raw.githubusercontent.com/5eanxlee/codexcli_notis/main/install.sh | bash

Or clone this repo and run:

./install.sh

The direct install command is equivalent to running install.sh from the repository. If you prefer to inspect the script first, clone the repo.

Restart any already-running Codex CLI sessions after installing so they reload ~/.codex/config.toml.

Terminal-Only Filtering

The top-level Codex notify hook is not TUI-only, so the installed notifier performs its own guard before sending an OS notification.

Defaults:

CODEX_NOTIFY_TERMINAL_ONLY=1
CODEX_NOTIFY_APP_WORKSPACE="$HOME/Documents/Codex"

To allow all Codex surfaces again:

CODEX_NOTIFY_TERMINAL_ONLY=0 ./install.sh

To keep terminal-only mode but use a different app workspace path:

CODEX_NOTIFY_APP_WORKSPACE="$HOME/Somewhere/Codex" ./install.sh

Test

./test.sh

The tests use temporary CODEX_HOME directories and fake OS notification commands. They do not modify your real ~/.codex.

What It Changes

It creates:

~/.codex/bin/codex-notify.py
~/.codex/log/codex-notify.log
~/.codex/log/codex-notify.last.json

It inserts a managed block near the top of:

~/.codex/config.toml

The previous config is backed up as:

~/.codex/config.toml.bak.YYYYMMDDHHMMSS

macOS Notification Settings

On macOS, the preferred sender is terminal-notifier, if installed. That is the app users should adjust in:

System Settings -> Notifications -> terminal-notifier

If terminal-notifier is not installed, the notifier falls back to AppleScript via osascript, which may show up under Script Editor or a related system entry.

Optional, recommended on macOS:

brew install terminal-notifier

Verify

After a Codex turn completes, check:

cat ~/.codex/log/codex-notify.last.json
cat ~/.codex/log/codex-notify.log

native_sent: true means the OS notification command succeeded.

Uninstall

./uninstall.sh

The uninstall script removes the managed block and the installed notifier script. It does not restore an older notify command automatically; use the timestamped backup if you need to restore previous config exactly.