Notificações do Claude Code no Windows (PowerShell e WSL)

01Windows nativo ou WSL: onde seus hooks rodam

O Claude Code roda nativamente no Windows ou dentro do WSL, e isso define como um hook de notificação funciona.

• Windows nativo. As configurações ficam em %USERPROFILE%\.claude\settings.json. Segundo a referência de hooks da Anthropic, hooks de comando rodam no Git Bash por padrão, ou no PowerShell quando o Git Bash não está instalado. Você pode forçar o PowerShell em um hook específico com "shell": "powershell"; aí o Claude Code usa o pwsh.exe (PowerShell 7) se encontrá-lo e, caso contrário, o powershell.exe (Windows PowerShell 5.1).
• WSL. Você instala e roda o claude dentro do terminal do WSL, então o arquivo de configurações é o do Linux, ~/.claude/settings.json dentro da sua distribuição, e os hooks rodam em um shell Linux. Ali, o notify-send normalmente não chega à área de trabalho do Windows. Chame programas do Windows em vez disso.

02O teste rápido: o bell do terminal

O sinal mais simples é o bell. Adicione isto ao seu arquivo de configurações:

{
  "preferredNotifChannel": "terminal_bell"
}

Assim, o Claude Code envia um caractere de bell quando termina ou fica esperando por você. No Windows Terminal, o que o bell faz é definido por perfil pelo bellStyle no settings.json dele. "bellStyle": ["window", "taskbar"] faz a janela e o botão da barra de tarefas piscarem em vez de tocar um som. O guia do bell do terminal tem mais detalhes sobre essa opção. Ela só ajuda enquanto o terminal está à vista.

03Um Notification hook com PowerShell

Este é o exemplo para Windows do guia de hooks da Anthropic. Funciona sem instalar nada:

{
  "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')\""
          }
        ]
      }
    ]
  }
}

Ele abre uma caixa de diálogo, não um toast no canto da tela, e a caixa pode abrir atrás do seu terminal. Teste o comando no PowerShell primeiro. Digite /hooks no Claude Code para conferir se o hook foi carregado.

O matcher vazio dispara para todos os tipos de notificação, incluindo permission_prompt (uma aprovação está esperando há cerca de seis segundos) e idle_prompt (o Claude terminou há cerca de 60 segundos). O guia do Notification hook explica esses tempos.

04Um toast de verdade com BurntToast

O BurntToast é um módulo de PowerShell bastante usado e mantido pela comunidade para notificações toast no Windows. Instale uma vez para o seu usuário:

Install-Module -Name BurntToast -Scope CurrentUser

Depois confira se funciona:

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

Use-o em um hook. Esta versão inicia o PowerShell sem perfil e ignora a execution policy só nesta chamada, então se comporta igual a partir do Git Bash ou do 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
          }
        ]
      }
    ]
  }
}

O hook Stop roda ao fim de cada turno, então você fica sabendo de uma tarefa concluída na hora, e não um minuto depois; veja o guia do Stop hook. "async": true roda o hook em segundo plano, para que uma inicialização lenta do PowerShell não trave o Claude Code.

Se os toasts nunca aparecem, confira Configurações > Sistema > Notificações: as notificações precisam estar ativadas e o Não Incomodar desativado. Os toasts do BurntToast normalmente aparecem ali sob Windows PowerShell, que também precisa ter as notificações permitidas.

05No WSL: chame o Windows via interop

Dentro do WSL o hook roda no Linux, mas o WSL consegue iniciar programas do Windows pelo nome .exe. O guia da Anthropic observa que o powershell.exe precisa estar no seu PATH via interop do Windows. Esse é o padrão; quem controla isso é o appendWindowsPath na seção [interop] do /etc/wsl.conf. Confira no seu shell do WSL:

command -v powershell.exe

Com o BurntToast instalado no lado do Windows, o hook no seu ~/.claude/settings.json do WSL é o mesmo comando:

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

Iniciar o Windows PowerShell a partir do WSL pode levar um segundo ou mais, outro motivo para usar "async": true.

06Onde o Claude Code Notifier se encaixa

Os hooks acima resolvem se você está na frente do computador. Eles não servem de nada quando você se afasta, e um toast não consegue aprovar um comando para o Claude.

O Claude Code Notifier é uma ferramenta independente (feita pela TouchTap, não pela Anthropic) construída sobre os hooks do Claude Code. A ferramenta de linha de comando gratuita dele, o ccn, roda em Mac, Windows e Linux; o suporte a Windows está em beta. No Windows nativo, instale pelo PowerShell:

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

Ele adiciona suas entradas de hook às configurações do Claude Code, não mexe no resto do arquivo e guarda um backup. Logo de cara, ele mostra um toast do Windows quando o Claude termina, precisa de uma permissão ou faz uma pergunta, sem precisar de celular nem de rede. Como ele se conecta ao Claude Code, e não a um terminal, funciona igual no Windows Terminal, no PowerShell e em terminais de IDE.

Se o Claude Code roda no WSL, instale o ccn dentro do WSL com a linha do Linux, porque é lá que estão o Claude Code e as configurações dele:

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

Depois rode ccn test. Se uma notificação disparada dentro do WSL chega ou não à sua área de trabalho do Windows depende da sua configuração do WSL, então no WSL o caminho confiável é o celular. Com um celular pareado, os eventos chegam como notificações push, e você pode permitir uma vez, permitir na sessão ou negar uma permissão, responder às perguntas do Claude e enviar a próxima instrução pelo celular. Veja como parear um celular, a página do ccn e os preços dos apps de celular.

Se você instalar o ccn, remova seus próprios hooks de toast para evitar notificações duplicadas.

07Perguntas frequentes