Codex CLI Windows Toasts on WSL2

Show a Windows BurntToast notification when a Codex CLI turn finishes inside WSL2, and also when Codex asks for permission escalation.

The notifier listens for Codex notify events, then calls Windows PowerShell from WSL and displays a toast with a small app logo beside the message.

Requirements

• Windows 10/11 with WSL2
• Codex CLI installed in WSL
• python3 in WSL
• Windows PowerShell available from WSL as powershell.exe
• Internet access the first time BurntToast is installed

Install

From this repository in WSL:

chmod +x install.sh
./install.sh

The installer will:

1. Copy the notifier to ~/.codex/notify-windows-toast/.
2. Install the Windows PowerShell BurntToast module for the current Windows user if it is missing.
3. Add this top-level setting to ~/.codex/config.toml:

notify = ["python3", "/home/YOU/.codex/notify-windows-toast/notify_windows_toast.py"]

notify must be at true TOML top level, before any [table] section. If it is placed after a header like [mcp_servers.codegraph.tools.codegraph_search], then it becomes part of that table and Codex will not use it as the global notify hook.

Restart Codex CLI after installing so it reloads config.toml.

Test

Run:

python3 ~/.codex/notify-windows-toast/notify_windows_toast.py --test

You should see a Windows toast titled Codex [your-project] [your-branch] for normal turn completion when the current session is inside a git checkout. Outside git, it falls back to Codex [current-directory].

To test the permission-style notification path:

python3 ~/.codex/notify-windows-toast/notify_windows_toast.py --test-approval

That path uses the title Codex appr [your-project] [your-branch], or Codex appr [current-directory] outside git.

Manual BurntToast Install

If you prefer installing BurntToast yourself, run this from WSL:

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "Install-Module BurntToast -Scope CurrentUser -Force -AllowClobber"

Then verify:

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "Import-Module BurntToast; 'BurntToast OK'"

How It Works

Codex passes a JSON event to the configured notify command. This script handles:

{"type":"agent-turn-complete"}

and also permission/escalation-shaped events whose type or fields indicate an approval request, such as:

{"type":"permission-request","justification":"...","sandbox_permissions":"require_escalated"}

For turn-complete events, it extracts last-assistant-message. For permission requests, it prefers justification, reason, message, and command/cmd. It then detects the current project directory and git branch from the session working directory when available, copies the logo PNG from WSL into Windows %TEMP%, and calls:

New-BurntToastNotification -Text @('Codex [your-project] [your-branch]', $message) -AppLogo $appLogo

The copy into Windows temp is deliberate. BurntToast can be unreliable with WSL UNC paths, while a local Windows temp path works consistently.

Troubleshooting

If python3 ~/.codex/notify-windows-toast/notify_windows_toast.py --test shows a toast but normal Codex turns do not, the usual cause is that notify = [...] was written inside a TOML table instead of at file top level.

Customize Logo

Replace:

~/.codex/notify-windows-toast/assets/codex-ai-sketch-logo.png

Keep it square. 256x256 PNG is a good size for the toast app-logo slot.