Notificações nativas do Claude Code: o bell do terminal e o preferredNotifChannel

01A solução rápida

Se você não ouve nada quando o Claude termina, adicione isto ao ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

Depois, confira se o seu terminal faz algo com o bell: tocar um som, fazer o ícone pular no Dock, piscar a aba ou mostrar uma notificação. Essa configuração fica no terminal, não no Claude Code. No Mac, no Windows e no Linux, a maioria dos terminais tem uma seção de "bell" ou "alerta" nas preferências.

02Todos os valores de preferredNotifChannel

A configuração pode ficar em qualquer arquivo de settings: de usuário (~/.claude/settings.json), de projeto (.claude/settings.json) ou local (.claude/settings.local.json). Versões antigas guardavam isso em ~/.claude.json, e o Claude Code ainda lê um valor que tenha ficado lá.

03Quando a notificação nativa dispara

Segundo a documentação da Anthropic, o alerta nativo segue o mesmo timing do hook Notification. Em uma sessão no terminal:

• Prompt de permissão: depois que o prompt fica uns seis segundos esperando sem nenhuma tecla pressionada. Cada tecla reinicia a contagem.
• Finalizado: cerca de 60 segundos depois que o Claude para, e só se você não digitou nada desde então e nenhum agente em segundo plano ainda estiver rodando.

Ou seja, o alerta nativo de "finalizado" não é instantâneo de propósito. A ideia é te alcançar quando você saiu de perto, não te avisar enquanto você está olhando. Se você quer um alerta assim que um turno termina, use um hook Stop (veja o guia do Stop hook).

04Terminal por terminal

iTerm2 (macOS)

O iTerm2 recebe notificação de desktop por padrão, mas o iTerm2 só a exibe depois que você permite:

1. Abra Settings > Profiles > Terminal.
2. Marque Notification Center Alerts.
3. Clique em Filter Alerts e ative Send escape sequence-generated alerts.

Confira também se o iTerm2 tem permissão para mostrar notificações em Ajustes do Sistema > Notificações.

Apple Terminal (macOS)

O Apple Terminal não recebe notificação de desktop. Com "auto", o Claude Code envia um bell silencioso só quando encontra o Audible bell desligado no perfil da janela em primeiro plano. Aí o bell aparece como um flash na janela, ou como o ícone pulando no Dock se o Terminal estiver em segundo plano, caso a opção Visual bell ou a de pular no Dock esteja ativada no perfil.

Atenção a um detalhe. Se você aceitou o prompt de configuração do terminal na primeira execução do Claude Code, ele rodou o /terminal-setup, que desliga o bell sonoro no seu perfil do Apple Terminal. Para ouvir um som, defina "terminal_bell" e reative o Audible bell em Settings > Profiles > Advanced.

Ghostty e Kitty (macOS e Linux)

Os dois recebem notificação de desktop sem nenhuma configuração e a repassam para a central de notificações do sistema operacional.

Todo o resto

Windows Terminal, GNOME Terminal, Konsole, Alacritty, WezTerm, Warp e os terminais de IDE não recebem nada por padrão. Configure "terminal_bell" e ative o tratamento de bell do próprio terminal, ou use um hook. Os terminais de IDE têm suas próprias peculiaridades, abordadas no guia de VS Code, Cursor e JetBrains.

05Via SSH e dentro do tmux

A notificação desktop é uma sequência de escape interpretada pelo terminal no seu próprio computador, então ela chega até você mesmo quando o Claude Code roda em um servidor remoto via SSH. Ghostty e Kitty a repassam sem nenhuma configuração extra. O iTerm2 precisa das configurações de alerta mostradas acima.

Dentro do tmux, a sequência é descartada, a menos que você habilite o passthrough. Adicione isto ao ~/.tmux.conf e rode tmux source-file ~/.tmux.conf:

set -g allow-passthrough on

Sessões desanexadas são outro problema: se nenhum terminal estiver anexado, nada pode exibir o alerta. Veja o guia do tmux e notificações via SSH.

06O alerta nativo e os hooks juntos

Os hooks de Notification rodam junto com o alerta nativo; eles não o substituem. A documentação da Anthropic deixa claro que os hooks disparam mesmo com "notifications_disabled": a configuração só muda como o Claude Code avisa você, não se o seu hook roda. Isso permite uma divisão bem clara:

• Mantenha "auto" ou "terminal_bell" para o alerta enquanto você está na mesa.
• Adicione um hook para todo o resto, como um som do sistema, uma notificação desktop em um terminal que não recebe nenhuma ou um push no celular com o ntfy.
• Se um hook já exibe uma notificação desktop, configure "notifications_disabled" para não ver duas.

Por exemplo, isto toca um som no macOS sempre que o Claude precisar da sua atenção, em qualquer terminal:

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

Os equivalentes para Linux e Windows estão no guia do Linux e no guia do Windows.

07Limitações das opções nativas

• Fica restrito ao computador. O bell ou a notificação vem do terminal na sua tela. Foi até a cozinha, perdeu o aviso.
• Depende do terminal. Muitos terminais populares não recebem nada até você mudar uma configuração.
• Você não pode responder. Ele avisa que o Claude está esperando; você ainda precisa voltar ao teclado.

O Remote Control da Anthropic, com o app móvel do Claude, é a forma oficial de receber pushes no celular. O guia comparativo o analisa ao lado das outras opções.

08Onde o Claude Code Notifier se encaixa

Se você trabalha na sua mesa, o alerta nativo mais "terminal_bell" talvez seja tudo de que você precisa. O Claude Code Notifier é para quando você não está na mesa. A ferramenta de linha de comando dele, ccn, roda como um hook do Claude Code, então funciona em qualquer terminal no Mac, Windows e Linux, com ou sem configurações de bell. Sozinho, ele exibe uma notificação desktop quando o Claude termina, precisa de uma permissão ou faz uma pergunta. Com um celular pareado, você pode permitir ou negar permissões, responder às perguntas do Claude e enviar a próxima instrução pelo celular; e, se você digitou nos últimos 30 segundos, nada fica esperando no celular. Veja a página do ccn.

09Perguntas frequentes