Como receber uma notificação quando o Claude Code terminar

01O que o Claude Code faz por conta própria

O Claude Code já tenta avisar você quando parece que você saiu do terminal. Por padrão, ele envia uma notificação de desktop no iTerm2, Ghostty e Kitty, pode emitir um caractere de bell no Apple Terminal e não faz nada nos outros terminais. No iTerm2, você também precisa ativar as configurações de alerta antes que algo apareça.

Então, se você usa o terminal do VS Code, o Warp, o Windows Terminal ou a maioria dos terminais do Linux, normalmente não vai receber nada. Dá para forçar o bell do terminal com a configuração preferredNotifChannel, explicada no guia do bell do terminal. Para ter uma notificação de desktop de verdade em qualquer terminal, você precisa de um hook.

02Os dois hooks de que você precisa

Hooks são comandos que o Claude Code executa em pontos fixos de uma sessão. Dois deles importam aqui:

O Stop é o rápido. Ele roda no fim de cada turno, na hora. Os tipos de Notification dependem de você estar longe: cada tecla digitada os adia, então você não recebe alertas enquanto está olhando. Se quiser um sinal no instante em que o Claude pedir permissão, use o hook PermissionRequest, descrito no guia do PermissionRequest.

Para entender como os hooks funcionam em geral (eventos, matchers, arquivos de configuração, exit codes), veja Hooks do Claude Code explicados.

03Uma configuração funcional no macOS

Abra o ~/.claude/settings.json (crie o arquivo se ele não existir) e adicione isto. Se o arquivo já tiver um objeto hooks, adicione Stop e Notification como chaves dentro dele em vez de substituí-lo.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

O Stop não tem matcher, então dispara em todo turno. O matcher do Notification o limita aos dois tipos que significam "volte aqui".

Se nada aparecer, o macOS pode estar bloqueando o Script Editor, que o osascript usa para exibir notificações. Rode osascript -e 'display notification "test"' uma vez no Terminal, depois abra Ajustes do Sistema > Notificações, encontre o Editor de Scripts e ative Permitir Notificações.

04A mesma configuração no Linux e no Windows

Mantenha a estrutura JSON acima e troque as strings de command.

Linux (precisa de um daemon de notificações do desktop, então não funciona em servidor headless):

"command": "notify-send 'Claude Code' 'Claude has finished'"

Se o notify-send não estiver disponível, instale o libnotify-bin no Debian e no Ubuntu, ou o equivalente da sua distribuição. Para SSH e servidores, veja notificações via SSH.

Windows (PowerShell). O próprio exemplo da Anthropic abre uma caixa de mensagem em vez de um toast no canto da tela:

"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude has finished', 'Claude Code')\""

A caixa pode abrir atrás da janela do terminal, então teste o comando no PowerShell antes. No WSL, o powershell.exe precisa estar acessível via interop do Windows. O guia do Windows mostra outras opções.

05Confira se funciona

1. Digite /hooks no Claude Code. Seus hooks devem aparecer em Stop e Notification.
2. Peça algo rápido ao Claude. Quando ele responder, a notificação de Stop deve aparecer.
3. Peça algo que exija permissão, mude para outra janela e espere. A notificação de permission_prompt chega depois de uns seis segundos.

Alterações no settings.json normalmente são aplicadas na hora. Se um hook não aparecer em /hooks, verifique se o arquivo é um JSON válido (sem vírgulas sobrando, sem comentários). Inicie o Claude Code com claude --debug para ver o que cada hook fez. Há mais soluções no checklist de troubleshooting.

06Recebendo o alerta no celular

Uma notificação no desktop só ajuda se você estiver no computador. Quando você se afasta, precisa do alerta em outro lugar. Há três caminhos comuns:

• Um serviço de push que você mesmo roda, como o ntfy, chamado com curl a partir dos mesmos hooks. Barato e flexível. Veja o guia do ntfy.
• Um webhook de chat para Telegram, Slack ou Discord. Ótimo se você já vive no chat. Veja o guia de webhooks de chat.
• Claude Code Notifier, que configura os hooks para você e permite responder pelo celular.

As opções DIY resolvem bem se você só quer um aviso. O limite é que elas são unidirecionais: você fica sabendo que o Claude está esperando, mas ainda precisa voltar ao teclado para aprovar qualquer coisa.

O Claude Code Notifier é uma ferramenta independente (não é feita pela Anthropic) com duas partes: o ccn, uma ferramenta de linha de comando gratuita para Mac, Windows e Linux, e apps para iPhone e Android. Instale com uma linha:

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

No Windows, use irm https://claudecodenotifier.com/install.ps1 | iex no PowerShell (o suporte ao Windows está em beta). Outras opções, incluindo Homebrew, npx @touchtap/ccn e o plugin do Claude Code, estão na página do ccn.

A instalação adiciona sete entradas de hook, cada uma rodando ccn hook, mantém o resto do seu settings.json como estava e salva um backup único ao lado dele. Mesmo sem celular, o ccn mostra uma notificação no desktop quando o Claude termina, precisa de permissão ou faz uma pergunta. Essa parte é gratuita e funciona sem rede.

Pareie um celular com ccn pair e você também ganha:

• um push de "o Claude terminou" assim que um turno acaba;
• pedidos de permissão que você pode permitir uma vez, permitir para a sessão ou negar;
• as perguntas de múltipla escolha do Claude, respondidas pelo celular;
• um campo de follow-up para mandar a próxima instrução ao Claude logo que ele terminar.

Se você digitou nos últimos 30 segundos, nada espera pelo celular e o terminal pergunta normalmente. Os apps exigem assinatura ou compra vitalícia; veja os preços. Pareando um celular explica a configuração passo a passo.

07Perguntas frequentes