Notificações do Claude Code: saiba quando ele está esperando e quando terminou

“Uma sessão bloqueada parece exatamente igual a uma sessão concluída, então eu abro a errada primeiro.” Essa frase de um pedido de recurso do Claude Code resume tudo. Veja como receber um sinal diferente para cada caso.

Por Aslan, equipe Pet Island · Atualizado em 26 de out. de 2026 · 4 min de leitura

RESPOSTA CURTA

O Claude Code já emite uma notificação quando termina ou espera por permissão enquanto você está ausente, mas, por padrão, só o Ghostty, o Kitty e o iTerm2 a mostram como notificação na área de trabalho. Nos outros, defina "preferredNotifChannel": "terminal_bell". Para ter dois sons diferentes, use um hook Notification com o matcher permission_prompt para “precisa de você” e um hook Stop para “terminou”.

O que o Claude Code faz sozinho

Quando o Claude termina uma tarefa ou pausa em um prompt de permissão e você parece estar longe do terminal, ele dispara um evento de notificação. Por padrão, ele só transforma isso em notificação na área de trabalho no Ghostty, no Kitty e no iTerm2. No Windows Terminal, no terminal do VS Code, no Warp e nos demais, nada visível acontece até você configurar.

A solução mais simples é o sino do terminal:

~/.claude/settings.jsonCopiar

{

"preferredNotifChannel": "terminal_bell"

}

O que o sino faz depende do seu terminal. No Windows Terminal, a configuração bellStyle pode ser audible (o padrão), window, taskbar, all ou none. Com all, o Windows Terminal toca um som e faz o ícone da barra de tarefas piscar.

iTerm2: Settings → Profiles → Terminal → marque “Notification Center Alerts” e, em Filter Alerts, ative “Send escape sequence-generated alerts”.
tmux: adicione set -g allow-passthrough on ao ~/.tmux.conf, ou as notificações nunca chegam ao terminal externo.
Via SSH: a notificação na área de trabalho volta para a sua máquina local, então sessões remotas também podem alertar você.

O pedido de recurso de notificações do sistema (#26581, 34 votos) foi fechado como já disponível, apontando justamente para essa notificação integrada. O pedido de um sinal diferente para “esperando” e “terminou” (#94373) continua aberto. É aí que entram os hooks.

Dois eventos: Notification e Stop

Notification dispara quando o Claude Code envia uma notificação. O matcher dele é o tipo de notificação. Os dois que interessam são permission_prompt (o Claude precisa que você aprove o uso de uma ferramenta e o prompt já está esperando há cerca de seis segundos) e idle_prompt (o Claude terminou de responder há cerca de 60 segundos e você não digitou nada desde então).
Stop dispara sempre que o Claude termina de responder. Ele não dispara quando você interrompe; erros de API disparam StopFailure no lugar.

Os hooks rodam junto com a notificação integrada, sem substituí-la, então você pode manter as duas.

Windows: dois sons diferentes

No Windows, os hooks rodam no Git Bash ou, quando o Git Bash não está instalado, no PowerShell. Definir "shell": "powershell" acaba com a adivinhação. Esta configuração toca um bipe duplo agudo quando o Claude precisa de permissão e um bipe grave quando termina:

%USERPROFILE%\.claude\settings.jsonCopiar

{

"hooks": {

"Notification": [

{

"matcher": "permission_prompt",

"hooks": [

{ "type": "command", "shell": "powershell",

"command": "[Console]::Beep(1320, 150); [Console]::Beep(1320, 150)" }

]

}

"Stop": [

{

"hooks": [

{ "type": "command", "shell": "powershell",

"command": "[Console]::Beep(660, 300)" }

]

}

]

}

Console.Beep recebe uma frequência em hertz e uma duração em milissegundos e espera até o bipe acabar. O guia de hooks da Anthropic também mostra um exemplo para Windows que abre uma caixa de mensagem com System.Windows.Forms; a própria observação deles é que isso é uma caixa de diálogo, não uma notificação, e pode abrir atrás do terminal.

macOS e Linux

A documentação da Anthropic usa afplay no macOS:

~/.claude/settings.jsonCopiar

{

"hooks": {

"Notification": [

{

"matcher": "permission_prompt",

"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]

}

"Stop": [

{

"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Pop.aiff" }]

}

]

}

Para um alerta visível, use osascript -e 'display notification "Claude needs you" with title "Claude Code"' no macOS ou notify-send "Claude Code" "Claude needs you" no Linux.

Detalhes que poupam uma noite

O Stop dispara muito. Ele dispara toda vez que o Claude termina de responder, não só quando uma tarefa inteira acaba. Se isso for barulhento demais, use a notificação idle_prompt. Ela espera cerca de um minuto e só dispara se você não tiver digitado nada.
Leia o evento se precisar. A entrada de Notification inclui message, title e notification_type, então um script pode mostrar a solicitação real.
Agent view. Se você roda sessões em segundo plano com claude agents, ele avisa pelo mesmo preferredNotifChannel quando uma sessão passa a precisar de entrada, termina ou falha, e dispara o hook Notification com o tipo agent_needs_input ou agent_completed.
Status no terminal. Terminais que implementam o protocolo de status OSC 7501 podem mostrar se cada sessão do Claude Code está trabalhando, esperando ou concluída. O Claude Code v2.1.295 ou posterior informa isso automaticamente.
O hook não dispara no Windows? Veja Hooks do Claude Code não funcionam no Windows. Quase sempre o culpado é o shell.

Ver qual sessão é e responder

Um som avisa que algo aconteceu. Ele não diz de qual dos seus três terminais veio nem o que o Claude quer executar. O Pet Island dá a cada sessão do Claude Code um lugar em uma pequena ilha no topo da sua tela: trabalhando, esperando por você ou concluída. Um pedido de permissão chega com o comando ou o diff, e você permite ou nega ali mesmo; perguntas e planos funcionam do mesmo jeito. Um clique leva você ao terminal exato quando quiser olhar mais de perto.

PERGUNTAS FREQUENTES

O Claude Code tem notificações?

Sim. Quando ele termina ou espera por permissão enquanto você está ausente, dispara uma notificação. O Ghostty, o Kitty e o iTerm2 a mostram como notificação na área de trabalho por padrão; em outros terminais, defina preferredNotifChannel como "terminal_bell" ou adicione um hook Notification.

Como faço para ouvir um som quando o Claude Code termina?

Adicione um hook Stop que toque um som, por exemplo afplay no macOS ou [Console]::Beep no PowerShell no Windows.

Como diferencio “precisa de permissão” de “terminou”?

Use um hook Notification com o matcher permission_prompt para um som e um hook Stop para outro.

Por que não recebo notificações no Windows Terminal ou no VS Code?

Por padrão, o Claude Code só envia notificações na área de trabalho no Ghostty, no Kitty e no iTerm2. Defina preferredNotifChannel como "terminal_bell" ou use um hook.

As notificações funcionam dentro do tmux?

Sim, depois que você adiciona set -g allow-passthrough on ao ~/.tmux.conf.

Fontes

Todas as configurações e comportamentos desta página foram conferidos com estas páginas em 26 de outubro de 2026. Os agentes mudam rápido; se algo não bater mais, vale o que diz a página oficial.

CONTINUE LENDO

Windows