DEV Community

Cover image for A Windows toast when Claude Code needs you, with nothing to install (and the dash that broke it)
Fred 🍓
Fred 🍓

Posted on

A Windows toast when Claude Code needs you, with nothing to install (and the dash that broke it)

I usually have two or three Claude Code sessions open. The one that costs me time is never the one that's working. It's the one that has been sitting on a permission prompt for fifteen minutes in a window I'm not looking at.

Most notification setups I find are written for macOS. On Windows the usual answer is "install the BurntToast module". You don't have to: Windows PowerShell 5.1 ships with Windows and can show a real toast through built-in WinRT classes.

Here's the setup I tested with real Claude Code sessions (2.1.316, Windows 11), and the three things that broke on the way.

Pick the right hook

You want to know Hook When it fires
Claude needs a permission PermissionRequest the moment the prompt appears
Claude is done Stop at the end of every turn
Claude needs a permission (later) Notification, matcher permission_prompt after about 6 seconds without typing
Claude is idle Notification, matcher idle_prompt about 60 seconds after Claude finished

The Notification timings are from the hooks reference. For "it needs me right now", use PermissionRequest. A PermissionRequest hook that prints nothing makes no decision, so the normal prompt in the terminal stays exactly as it was. This hook only adds a toast.

The script

Save this as %USERPROFILE%\.claude\notify.ps1:

# notify.ps1 - a Windows toast for Claude Code hooks. Keep this file ASCII-only.
param([string]$Kind = 'waiting')

try {
  $in = [Console]::In.ReadToEnd() | ConvertFrom-Json
  $project = Split-Path $in.cwd -Leaf

  if ($Kind -eq 'done') {
    $text = 'Done'
  } elseif ($in.tool_input.command) {
    # Bash and PowerShell both pass the command here
    $cmd = [string]$in.tool_input.command
    if ($cmd.Length -gt 80) { $cmd = $cmd.Substring(0, 77) + '...' }
    $text = "Wants to run: $cmd"
  } elseif ($in.tool_name) {
    $text = "Wants to use $($in.tool_name)"
  } else {
    $text = 'Needs you'
  }

  [void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
  [void][Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime]

  $esc = { param($s) [Security.SecurityElement]::Escape([string]$s) }
  $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
  $xml.LoadXml("<toast><visual><binding template='ToastGeneric'><text>$(& $esc "Claude Code - $project")</text><text>$(& $esc $text)</text></binding></visual></toast>")

  $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
  # Same tag for the same session: a new toast replaces the old one
  $tag = ([string]$in.session_id) -replace '[^a-zA-Z0-9-]', ''
  if ($tag) { $toast.Tag = $tag.Substring(0, [Math]::Min(64, $tag.Length)); $toast.Group = 'claude-code' }

  # Borrow the AppUserModelID of Windows PowerShell, so there is nothing to register
  $app = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
  [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($app).Show($toast)
} catch { }
exit 0
Enter fullscreen mode Exit fullscreen mode

What it does:

  • Which session? The title is the project folder from cwd. With three sessions, "Claude Code - shop-frontend" is the whole point.
  • What does it want? For shell commands it shows the command: "Wants to run: npm test".
  • One toast per session. The toast Tag is the session id, so "Done" replaces "Wants to run: npm test" instead of stacking up. In my test the notification center held exactly one toast per session.
  • It never gets in Claude's way. Every error ends in exit 0, so a broken toast can't turn into a hook error.

The hooks

Merge this into %USERPROFILE%\.claude\settings.json (replace YOU with your Windows user name):

{
  "hooks": {
    "PermissionRequest": [
      { "hooks": [ { "type": "command", "command": "powershell.exe", "timeout": 10,
        "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:/Users/YOU/.claude/notify.ps1", "waiting"] } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "powershell.exe", "timeout": 10,
        "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:/Users/YOU/.claude/notify.ps1", "done"] } ] }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

args makes Claude Code start powershell.exe directly, with no shell in between. Without it, hook commands on Windows run through Git Bash if you have it installed, and Bash expands every $ in an inline PowerShell command before PowerShell ever sees it. A script file plus args avoids all of that quoting.

If your Claude Code doesn't know args yet, use one string and quote the path, not the program:

"command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"C:/Users/YOU/.claude/notify.ps1\" done"
Enter fullscreen mode Exit fullscreen mode

Restart your sessions after changing the settings. In my test, a real Stop showed "Claude Code - demo-project / Done", and a real permission request showed "Wants to run: node -e "console.log(42)"".

Three things that broke

1. An en dash killed the whole script. A typographic dash in a string ("Claude Code – $project") and nothing worked anymore: "The string is missing the terminator". Windows PowerShell 5.1 reads a .ps1 without a byte order mark as ANSI, which is Windows-1252 on my machine. The en dash is three bytes in UTF-8, E2 80 93, and 0x93 in Windows-1252 is a curly opening quote. PowerShell accepts curly quotes as real quotes, so the string ended in the middle of the dash. The same file saved with a BOM works. The simplest fix is the first line of the script: ASCII only.

2. An empty tag throws. When I tested with hand-written JSON that had no session_id, setting $toast.Tag = '' threw "The parameter is incorrect", and there was no toast. Hence the if ($tag).

3. async: true showed nothing in headless runs. Command hooks can run in the background with "async": true, and PowerShell takes about 0.6 s to start (607 to 673 ms in three runs on my laptop), so that was my first idea. In claude -p runs no toast ever appeared. My guess is that the session ended before PowerShell did. Synchronous with a 10-second timeout worked every time, and 0.6 s at the end of a turn doesn't hurt. I haven't tried async in an interactive session.

Two smaller ones: I only tested Windows PowerShell 5.1 (powershell.exe), not PowerShell 7. And if nothing shows up at all, check Do not disturb: Windows then sends toasts straight to the notification center without showing them.

What it can't do

  • Answer the prompt. Buttons on a toast need an app that handles them. If you want to answer from somewhere else, the same PermissionRequest hook can return a decision. I wrote about that in Approve Claude Code permission prompts from anywhere.
  • Bring the right terminal to the front when you click it.

Or let an app do it

Full disclosure: I build VibeDesk, a free, open-source Windows app around Claude Code. It shows a status dot per session (yellow means "needs you") and turns permission prompts into cards with Allow and Deny, also on a paired phone. But if a toast is all you want, the script above is all you need. The website has a longer guide to Claude Code notifications on Windows, including a beep-only version.

How do you notice a waiting session today? A) a sound B) a toast C) I check by hand D) I don't, and lose twenty minutes

Top comments (0)