Claude Code notifications on Windows (PowerShell and WSL)

01Native Windows or WSL: where your hooks run

Claude Code runs either natively on Windows or inside WSL, and this decides how a notification hook works.

• Native Windows. Settings live in %USERPROFILE%\.claude\settings.json. According to Anthropic's hooks reference, command hooks run in Git Bash by default, or in PowerShell when Git Bash is not installed. You can force PowerShell for a single hook with "shell": "powershell"; Claude Code then uses pwsh.exe (PowerShell 7) if it finds it, and powershell.exe (Windows PowerShell 5.1) otherwise.
• WSL. You install and run claude inside the WSL terminal, so the settings file is the Linux one, ~/.claude/settings.json inside your distribution, and hooks run in a Linux shell. notify-send there does not usually reach the Windows desktop. Call Windows programs instead.

02The quick test: the terminal bell

The cheapest signal is the bell. Add this to your settings file:

{
  "preferredNotifChannel": "terminal_bell"
}

Claude Code then sends a bell character when it finishes or waits for you. In Windows Terminal, what the bell does is set per profile by bellStyle in its settings.json. "bellStyle": ["window", "taskbar"] flashes the window and the taskbar button instead of playing a sound. The terminal bell guide has more on this route. It only helps while the terminal is in view.

03A Notification hook with PowerShell

This is the Windows example from Anthropic's hooks guide. It works without installing anything:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

It opens a dialog box, not a toast in the corner of the screen, and the dialog can open behind your terminal. Test the command in PowerShell first. Type /hooks in Claude Code to check the hook is loaded.

The empty matcher fires for every notification type, including permission_prompt (an approval has waited about six seconds) and idle_prompt (Claude finished about 60 seconds ago). The Notification hook guide explains the timing.

04A real toast with BurntToast

BurntToast is a widely used, community-maintained PowerShell module for Windows toast notifications. Install it once for your user:

Install-Module -Name BurntToast -Scope CurrentUser

Then check it works:

New-BurntToastNotification -Text 'Claude Code', 'Claude needs your attention'

Use it in a hook. This version starts PowerShell with no profile and bypasses the execution policy for this one call, so it behaves the same from Git Bash or PowerShell:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"New-BurntToastNotification -Text 'Claude Code', 'Claude needs your attention'\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"New-BurntToastNotification -Text 'Claude Code', 'Claude has finished'\"",
            "async": true
          }
        ]
      }
    ]
  }
}

The Stop hook runs at the end of every turn, so you hear about a finished task at once rather than a minute later; see the Stop hook guide. "async": true runs the hook in the background so a slow PowerShell start does not hold Claude Code up.

If toasts never appear, check Settings > System > Notifications: notifications must be on, and Do Not Disturb must be off. BurntToast toasts usually appear there under Windows PowerShell, which also needs its notifications allowed.

05From WSL: call Windows through interop

Inside WSL the hook runs in Linux, but WSL can start Windows programs by their .exe name. Anthropic's guide notes that powershell.exe must be on your PATH through Windows interop. That is the default; it is controlled by appendWindowsPath in the [interop] section of /etc/wsl.conf. Check from your WSL shell:

command -v powershell.exe

With BurntToast installed on the Windows side, the hook in your WSL ~/.claude/settings.json is the same command:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -Command \"New-BurntToastNotification -Text 'Claude Code', 'Claude has finished'\"",
            "async": true
          }
        ]
      }
    ]
  }
}

Starting Windows PowerShell from WSL can take a second or more, which is another reason for "async": true.

06Where Claude Code Notifier fits

The hooks above are fine if you are at your desk. They do nothing once you walk away, and a toast cannot approve a command for Claude.

Claude Code Notifier is an independent tool (made by TouchTap, not by Anthropic) built on Claude Code's hooks. Its free command line tool, ccn, runs on Mac, Windows and Linux; Windows support is in beta. On native Windows, install it from PowerShell:

irm https://claudecodenotifier.com/install.ps1 | iex

It adds its hook entries to your Claude Code settings, leaves the rest of the file untouched and keeps a backup. Straight away it shows a Windows toast when Claude finishes, needs a permission or asks a question, with no phone and no network needed. Because it hooks into Claude Code, not into a terminal, it works the same in Windows Terminal, PowerShell and IDE terminals.

If Claude Code runs in WSL, install ccn inside WSL with the Linux line, because that is where Claude Code and its settings are:

curl -fsSL https://claudecodenotifier.com/install.sh | sh

Then run ccn test. Whether a desktop notification from inside WSL reaches your Windows desktop depends on your WSL setup, so for WSL the phone is the reliable route. With a phone paired, events arrive as push notifications, and you can allow once, allow for the session or deny a permission, answer Claude's questions and send the next instruction from the phone. See pairing a phone, the ccn page and pricing for the phone apps.

If you install ccn, remove your own toast hooks to avoid duplicate notifications.

07FAQ