CLI: add native Linux desktop notifications via Freedesktop/libnotify

What variant of Codex are you using?

CLI / TUI on Linux.

What feature would you like to see?

Please add a native Linux desktop notification backend for Codex TUI notifications, using the Freedesktop Notifications DBus API directly or via a supported notify-send/libnotify equivalent.

Today the TUI notification path emits terminal-level notifications, such as OSC 9 in supported terminals and BEL as a fallback. That works for some terminals, but it does not integrate cleanly with Linux notification daemons such as mako, dunst, or desktop shell notification centers.

A useful shape would be something like:

[tui]
notifications = ["agent-turn-complete", "approval-requested", "plan-mode-prompt"]
notification_method = "freedesktop" # or "libnotify" / "desktop"
notification_condition = "unfocused"

Expected behavior:

• On Linux desktop sessions, Codex sends a proper desktop notification through org.freedesktop.Notifications.
• The app name is recognizable, for example Codex.
• The same existing TUI notification events are supported:
• agent-turn-complete
• approval-requested
• plan-mode-prompt
• The existing notification_condition behavior still applies.
• If DBus/libnotify is unavailable, Codex either falls back to the configured terminal method or logs a clear diagnostic.

Why this matters

Terminal notification protocols can have awkward side effects on Linux desktop environments. In my case:

• environment: Arch Linux, Hyprland/Omarchy, kitty, tmux, mako;
• Codex CLI: codex-cli 0.137.0;
• terminal notifications worked as terminal alerts, but did not become libnotify notifications;
• the terminal alert path could also interact with focus/urgency behavior, requiring Hyprland/kitty configuration to avoid focus disruption.

The clean user experience would be for Codex to send desktop notifications directly when that is what the user configured, rather than relying on terminal escape sequences or bells.

Current workaround

I can work around this with a custom adapter:

notify = ["/path/to/codex-libnotify"]

[[hooks.PermissionRequest]]
matcher = "*"

[[hooks.PermissionRequest.hooks]]
type = "command"
command = "/path/to/codex-libnotify"
timeout = 5
statusMessage = "Sending desktop notification"

[tui]
notifications = false

The script receives either the legacy agent-turn-complete notify payload or the PermissionRequest hook JSON, then calls notify-send with the correct DBus environment.

That workaround proves the local desktop notification stack is fine, but it is still a workaround because it requires:

• a user-maintained script;
• two separate Codex config surfaces (notify for completion, hooks for permission requests);
• hook trust/review for approval-request notifications;
• manual DBus environment handling in some launch contexts;
• disabling terminal notifications to avoid duplicate OSC/BEL alerts.

Related issues

This is related to but narrower than:

• #19921, which asks to expose plan-mode-prompt and approval-requested through top-level notify.
• #16484, which asks for a broader machine-readable external event surface.
• #8189, which covers WSL-specific notification delivery failures.

This request is specifically for a first-class Linux desktop notification backend for the existing TUI notification events, so users can choose desktop notifications instead of terminal OSC/BEL behavior.