Claude Code and Codex notifications on Windows and WSL

Which road does your toast take?

Phone push and webhooks do not depend on any of this, and neither does the Claude Code bell (Claude Code writes it itself), so they still arrive when a toast cannot. The terminal bell for other agents is a separate path: on native Windows it also runs through pwsh.

Native Windows: PowerShell 7 and BurntToast

On Windows every toast is sent by pwsh (PowerShell 7) running anotifier's toast.ps1, which uses the BurntToast module. PowerShell 7 installs side by side with the Windows PowerShell 5.1 that ships with Windows and does not replace it. powershell.exe on its own cannot send these toasts. Install PowerShell 7 with winget, then run setup:

winget install --id Microsoft.PowerShell --source winget
npx anotifier@latest setup
npx anotifier@latest test toast

What setup does for the toast on Windows:

• Writes the hooks for each agent it finds: Stop and Notification for Claude Code in ~/.claude/settings.json, and Stop, PermissionRequest and SessionStart for Codex in %USERPROFILE%\.codex\hooks.json. Each hook is one node command that runs anotifier's notify.mjs. Claude Code runs a hook command with Git Bash on Windows, or with PowerShell when Git Bash is not installed.
• Checks for pwsh. If it is there, it installs BurntToast for your user with Install-Module BurntToast -Scope CurrentUser when the module is missing. Nothing is installed while a hook runs.
• If pwsh is missing, or the BurntToast install fails, it turns the toast channel off and prints the winget command. status then shows toast: off, no backend. Phone push and webhooks stay on. Run setup again once PowerShell 7 is installed and the toast comes back on; a toast you switched off yourself stays off.

• Each toast carries the agent's own icon and a title like my-app · Claude Code.
• Sounds are the Windows notification sounds: Default, IM, Mail, Reminder, SMS, Alarm. Finished tasks play IM; approvals and questions play Reminder. Change them per event with events.<event>.toastSound.
• A toast has 7 seconds to send. If BurntToast is missing or fails, you hear the Windows exclamation sound instead of seeing a toast, and the failure is logged to ~/.anotifier/errors.log as toast:windows with the cause (pwsh not found, exit code 3, or timed out after 7000 ms).

Click-to-focus

Clicking a native toast brings the terminal or editor that ran the agent to the front, so an approval prompt is one click away. When the hook knows the project name or working directory, the toast carries an agentfocus:// link, and on the first toast anotifier registers a handler for it under HKCU\Software\Classes\agentfocus. Clicking the toast runs pwsh to choose a window:

1. It looks at visible windows whose title contains the project folder name.
2. Among those it prefers one whose title also names a terminal (Windows Terminal, PowerShell, cmd, Warp, WezTerm and similar), then a Visual Studio Code window, then a Cursor window, then any other match.
3. If no title matches, it falls back to the window that toast.ps1 found by walking up the process tree from the hook, as long as that window still exists.

So a custom terminal tab title that drops the folder name sends the click to the fallback window. To turn click-to-focus off:

{ "toast": { "clickToFocus": false } }

Inside WSL: how the toast crosses into Windows

A Linux process in WSL cannot draw a Windows notification, so anotifier asks Windows to do it. It detects WSL from the kernel version string, /proc/version, the WSL_INTEROP and WSL_DISTRO_NAME variables, or other WSL markers (Docker containers are not mistaken for WSL) and uses the Windows path instead of notify-send. Microsoft documents the mechanism it relies on: WSL can run Windows tools from the Linux command line as tool-name.exe. The steps:

1. wslpath -w converts the path of anotifier's toast-wsl.ps1 into a Windows path such as \\wsl.localhost\Ubuntu\…, so Windows PowerShell can open a file that lives inside the distribution.
2. It runs a PowerShell with -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File and the title and message as typed parameters, never -Command. It tries these in order until one works: /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe, then powershell.exe on the PATH, then /mnt/c/Program Files/PowerShell/7/pwsh.exe, then pwsh.exe on the PATH.
3. toast-wsl.ps1 calls the Windows toast API directly, using PowerShell's own registered app identity. That is why it needs no BurntToast and shows under Windows PowerShell's name.

The result is deliberately simple: the title and the message, with no per-agent icon, custom sound or click-to-focus. Each attempt has 7 seconds. A failure is logged to ~/.anotifier/errors.log as toast:wsl; when none of the four works, the entry lists each one it tried.

• Run npx anotifier@latest setup inside the distribution. Agents in WSL read their settings from the Linux home directory, so a Windows-side setup does not wire them. Claude Code's own setup page says the same for the agent: install and launch claude inside the WSL terminal, not from PowerShell or CMD.
• Interop must be on. It is by default: the [interop] section of /etc/wsl.conf has enabled (default true) and appendWindowsPath (default true). With enabled = false there is no route to a toast. With only appendWindowsPath = false, the two absolute /mnt/c paths above do not depend on the PATH, so they are still tried while C: is mounted at /mnt/c.
• Changes to wsl.conf apply only after WSL has fully stopped. Run wsl --shutdown from PowerShell, then open the distribution again.
• setup looks for a reachable PowerShell. If it finds none, it turns the toast channel off and tells you to enable interop. Run setup again once it works.

Do you need wsl-notify-send?

No. anotifier never calls wsl-notify-send. It runs PowerShell directly, so there is nothing to download and nothing to put on your PATH. wsl-notify-send is a separate prebuilt Windows executable that accepts a few notify-send options. It is useful when you write your own hook and want a drop-in notify-send inside WSL. The wsl-notify-send guide compares it with calling powershell.exe yourself, shows the toast script, and wires either one to Claude Code and Codex.

Both give the same kind of toast: a title and a message under a generic app name. The native Windows road is the one with the icon, sound and click-to-focus.

WSLg and WSL notifications

WSLg is Microsoft's support for running Linux GUI applications on Windows. Microsoft's documentation lists it for WSL 2 on Windows 10 build 19044 or later and on Windows 11, and describes GUI apps, not desktop notifications. anotifier does not depend on it. The toast is raised by Windows through interop, so you do not need WSLg, a notification daemon or D-Bus inside the distribution for it to work.

Do not disturb and Focus Assist

A common reason for Toast sent with nothing on screen is Windows itself holding the banner back. Windows 11 calls the feature Do not disturb (Focus assist on older builds). While it is on, Windows shows banners only for alarms, reminders and the apps you allow, and sends everything else to the notification center, so a missed toast is usually waiting there. anotifier does not detect it, and test toast reports Toast sent whenever the PowerShell call succeeds.

• Turn it off from the notification center (the bell icon), or allow the sender under Settings > System > Notifications, in the Do not disturb Apps list (Add apps).
• It can switch on by itself. Under Turn on do not disturb automatically, Windows lists rules for certain times of day, when duplicating the display, when playing a game, when using an app in full-screen mode, and for the first hour after a Windows feature update.
• Per-app settings matter too. On Settings > System > Notifications, under Notifications from apps and other senders, open the sender and check that notifications and Show notification banners are on, and Play a sound if you want the ding. For a WSL toast the sender is Windows PowerShell.

Windows toast not showing? Fixes by symptom

Start with anotifier status, which prints the last 8 hook errors from ~/.anotifier/errors.log, then match what you see:

"Terminal process wsl.exe terminated with exit code: -1"

This message is not an anotifier error. VS Code prints "The terminal process … terminated with exit code" when the shell it launched exits, and here the shell is wsl.exe. anotifier never starts wsl.exe: on Windows it runs pwsh, and from inside WSL it runs powershell.exe, and its own failures go to errors.log as toast:windows or toast:wsl.

VS Code's terminal troubleshooting page covers the WSL case. Run wsl --status and wsl --list --verbose in PowerShell outside the editor to see whether WSL starts at all. Use a real Linux distribution rather than a Docker-managed one such as docker-desktop-data, set the default with wsl --set-default "<distribution-name>", and update a terminal profile that names a distribution with -d. That page documents exit code 1 for WSL and does not explain -1, so this guide cannot tell you what -1 means. If WSL itself starts but the toast does not appear, the table above applies.

Send a test toast

npx anotifier@latest test toast   # real toast: prints Toast sent or Toast failed
npx anotifier@latest doctor       # PowerShell 7, BurntToast, execution policy (WSL: wslpath, PowerShell)
npx anotifier@latest status       # wired agents, the toast backend and the last 8 errors

• test toast uses the same backend as the hooks and exits with code 1 when it fails. It skips the agent's hook, snooze and quiet hours, and it ignores toast.enabled, so it can pass while real alerts are off. status shows whether the toast channel is on.
• On Windows, doctor fails when PowerShell 7 is missing, warns when BurntToast is not installed, and fails on a blocking Group Policy execution policy. In WSL it checks for wslpath and a reachable Windows PowerShell. doctor --deep has no read-back on Windows or WSL, so test toast is the real delivery check.
• To test BurntToast without anotifier, run pwsh -NoProfile -Command "New-BurntToastNotification -Text 'Test','Hello'". To test the WSL road by hand, use the script in the wsl-notify-send guide.
• If the test works and real alerts do not, the problem is between the agent and anotifier. Restart the agent so it reloads its hooks, and see the troubleshooting guide.

Related Windows guides: Claude Code notification sounds on Windows and WSL, Codex CLI notifications on Windows, and Cursor notifications on Windows and WSL.

Try it

One command wires every agent you have installed: Claude Code, Codex CLI, Cursor, and Gemini CLI.

npx anotifier@latest setup

Other guides

Claude CodeCodex CLICursorGemini CLIClaude Code permissionsClaude Code soundsClaude Code usage limitsClaude Code auto-compactClaude Code hooks securityccnotifyCodex CLI soundsAntigravity CLImacOS & LinuxAgent hooksTroubleshootingntfy phone pushWSL Windows toast