Codex Notifier

Ubuntu desktop notifier for Codex CLI sessions.

It watches the local session JSONL files under ~/.codex/sessions and raises native notifications when Codex is waiting on you instead of silently finishing in another terminal.

It notifies when:

• a Codex turn reaches final_answer
• Codex asks for explicit user input
• Codex is actually waiting on an approval prompt

The runtime stays dependency-light and uses tools already present on a typical Ubuntu desktop:

• notify-send for desktop notifications
• pw-play, aplay, or canberra-gtk-play for audio

Features

• native Ubuntu notifications with a custom app icon
• configurable sound profiles: quiet, balanced, loud
• autostart installation for login sessions
• resume-safe offset tracking so restarts do not replay old sessions
• approval alert grace period to avoid false positives from already-approved commands

Sound behavior

• normal completion notifications play a single soft prompt
• critical approval/input notifications play a slightly stronger double prompt
• --no-sound disables audio entirely

Install

From this repository:

./install.sh
~/.local/bin/codex-notifier --test-notification

install.sh does three things:

• creates ~/.local/bin/codex-notifier
• installs the icon under ~/.local/share/icons/...
• adds a desktop autostart entry at ~/.config/autostart/codex-notifier.desktop

After that, Ubuntu will start it automatically on login.

To persist a different sound profile in autostart:

./install.sh quiet
./install.sh balanced
./install.sh loud

How It Works

codex_notifier.py tails Codex session files, extracts assistant final answers and approval/input events from the JSON stream, and emits notifications only for new content. Offsets are stored in ~/.cache/codex-notifier/state.json so restarts continue cleanly.

Manual usage

Run it in the foreground:

./codex_notifier.py

Useful options:

./codex_notifier.py --dry-run
./codex_notifier.py --sound-profile quiet
./codex_notifier.py --sound-profile loud --test-notification
./codex_notifier.py --no-final-answer
./codex_notifier.py --watch ~/.codex/sessions
./codex_notifier.py --watch ~/.codex/sessions/2026/03/06/some-session.jsonl --read-existing --once --dry-run

Notes

• By default, newly discovered files start at their current end, so you do not get spammed with old notifications when the watcher starts.
• Offsets are persisted in ~/.cache/codex-notifier/state.json, so restarts resume cleanly.
• Approval requests are delayed very briefly before notifying. This avoids false alerts for commands that were already auto-approved and started immediately.

Upload Checklist

• create the GitHub repo
• add origin
• push main
• choose a license before publishing publicly

Remove

Delete these files:

rm -f ~/.local/bin/codex-notifier
rm -f ~/.config/autostart/codex-notifier.desktop
rm -f ~/.local/share/applications/codex-notifier.desktop
rm -f ~/.local/share/icons/hicolor/scalable/apps/codex-notifier.svg
rm -rf ~/.cache/codex-notifier