Notificações do Claude Code não funcionam? Um checklist

011. Verifique se o Claude Code carregou o hook

Digite /hooks no prompt do Claude Code. É um navegador somente leitura de todos os hooks que o Claude Code carregou, e ele indica a origem de cada um: configurações do usuário, do projeto, locais, de um plugin ou da sessão atual. Selecione um hook para ver o comando exato e o arquivo onde ele está definido.

Se o seu hook não está na lista:

• O JSON é inválido. Os arquivos de configuração são JSON estrito. Uma vírgula sobrando ou um comentário // quebra o arquivo, e o Claude Code mostra um Settings Error na próxima inicialização. Rode claude doctor para ver as entradas que o Claude Code rejeitou.
• O arquivo está no lugar errado. Hooks pessoais ficam em ~/.claude/settings.json (no Windows, %USERPROFILE%\.claude\settings.json). Hooks de projeto ficam em .claude/settings.json dentro do projeto. Rode /status e leia a linha Setting sources para ver quais arquivos foram carregados.
• O nome do evento está errado. Nomes de evento diferenciam maiúsculas de minúsculas: Notification, Stop, PermissionRequest. Um nome de evento desconhecido aparece como Settings Warning e é ignorado.
• Os hooks estão desativados. "disableAllHooks": true em qualquer arquivo de configuração desativa todos os hooks. Se o /hooks mostrar Only hooks from managed settings run here, sua organização definiu allowManagedHooksOnly e seus próprios hooks não vão rodar.
• A edição não foi detectada. Normalmente o Claude Code recarrega as configurações sozinho. Se o hook não aparecer depois de alguns segundos, reinicie a sessão.

022. Aceite a confiança no workspace

Numa sessão interativa, o Claude Code segura os hooks de todos os arquivos de configuração, inclusive do seu ~/.claude/settings.json, até você aceitar o diálogo de confiança no workspace para a pasta. Se você fechou esse diálogo, ou está numa pasta em que nunca abriu o Claude Code, seus hooks não vão rodar ali. Inicie o claude nessa pasta e aceite o diálogo.

033. Confirme que o evento dispara quando você acha que dispara

Muitas notificações "quebradas" são, na verdade, questão de timing. Segundo a referência de hooks da Anthropic:

Então, se você testar um hook de Notification enquanto digita no terminal, ele pode nunca disparar. Mude para outra janela e espere. Para um alerta no instante em que o turno termina, use Stop; o guia do Stop hook explica como.

Confira também seu modo de permissão. Versões recentes do Claude Code iniciam sessões interativas no modo auto, em que um classificador aprova a maioria das ações sem perguntar. Sem prompt, não há notificação de permission_prompt nem hook de PermissionRequest. Para testar alertas de permissão, pressione Shift+Tab até a barra de status mostrar o modo manual e peça ao Claude algo que precise de aprovação. Modos de permissão explicados tem os detalhes.

Matchers também diferenciam maiúsculas de minúsculas. Um matcher de PermissionRequest com bash não casa com a ferramenta Bash.

044. Rode o comando do hook você mesmo

Copie o comando do /hooks e rode num terminal com uma entrada de exemplo:

echo '{"hook_event_name":"Stop","cwd":"/tmp","last_assistant_message":"done"}' | ./my-hook.sh
echo $?

Falhas comuns:

• command not found: use um caminho absoluto para o script, ou ${CLAUDE_PROJECT_DIR} para scripts do projeto.
• O script não faz absolutamente nada: torne-o executável com chmod +x ./my-hook.sh.
• jq: command not found: instale o jq, ou faça o parse do JSON com Python ou Node.js.

055. Leia o log de debug

Inicie o Claude Code com claude --debug. Nada a mais aparece no terminal; o log vai para ~/.claude/debug/<session-id>.txt. Para escolher o caminho, use claude --debug-file /tmp/claude.log e rode tail -f /tmp/claude.log em outro terminal. Se a sessão já estiver rodando, o /debug ativa o log e mostra onde ele está.

Procure linhas que começam com Hooks:. Cada uma mostra o evento, o comando, como terminou (finished with status 0, timed out, failed to start) e quanto tempo levou. Para mais detalhes sobre o matching, defina CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

Dois problemas só aparecem aqui:

• Seu profile do shell imprime alguma coisa. Se o ~/.bashrc ou o ~/.zshrc roda um echo e o shell carrega esse arquivo, o texto vai parar antes da saída JSON do hook, e o Claude Code trata a saída como texto puro. Procure no log por Hook output does not start with {. Envolva a saída do profile em if [[ $- == *i* ]]; then ... fi para que ela só rode em shells interativos.
• Não há terminal para escrever. No Mac e no Linux, command hooks rodam sem terminal de controle. Um hook que tenta tocar o bell ou escrever escape codes em /dev/tty falha em silêncio. Use um comando de notificação de desktop, ou a configuração preferredNotifChannel do próprio Claude Code, explicada no guia do terminal bell.

066. Verifique o sistema operacional

Se o log de debug disser que o hook terminou com status 0 e mesmo assim nada apareceu, foi o sistema operacional que escondeu a notificação. Verifique se o app que exibe o alerta tem permissão para mostrar notificações e se o Foco (Mac), o Não incomodar (Windows) ou a opção de não perturbe do seu desktop Linux está desligado. No Linux, é preciso ter um daemon de notificações rodando.

Os comandos específicos de cada plataforma estão nos guias para macOS, Windows e Linux.

07Se você usa o Claude Code Notifier

O Claude Code Notifier é uma ferramenta independente (não feita pela Anthropic) que instala um pequeno programa, o ccn, como hooks do Claude Code. Tudo o que foi dito acima continua valendo, porque o ccn é um hook como qualquer outro. Comece pelas verificações dele:

1. ccn doctor verifica os hooks, as credenciais, a conexão com o servidor e a detecção de presença. Corrija primeiro qualquer problema que ele apontar.
2. ccn test envia uma notificação de teste. Se ela chegar, o problema está no evento ou em alguma configuração, não no pipeline.
3. ccn devices lista os celulares pareados com este computador. Se nenhum aparecer, pareie de novo com ccn pair; o guia de pareamento explica o passo a passo.
4. ccn config show mostra as configurações em vigor. Confirme que notify_on_done, notify_on_permission e notify_on_question estão ativados e que quiet_hours não cobre o horário atual. Configurações alteradas no celular chegam ao computador com ccn sync.

Alguns comportamentos parecem defeito, mas são intencionais:

• Você está no teclado. Se você digitou algo nos últimos 30 segundos, nada espera pelo celular e o terminal pergunta normalmente. Com quiet_when_present ativado (o padrão), o celular não recebe nada enquanto você está no terminal em que o Claude roda, e recebe um card informativo se você estiver ativo em outro app.
• Alertas duplicados ou faltando no Mac. Não rode o antigo app da barra de menus do Mac e o ccn no mesmo Mac.
• Um longo período sem uso. Se um celular ou computador ficar 60 dias sem uso, o servidor apaga o pareamento, e você precisa parear de novo.

No próprio celular, verifique se as notificações estão permitidas para o app e se o Foco (iPhone) ou o Não perturbe (Android) não está silenciando os alertas. No Android, a otimização de bateria pode atrasar notificações de alguns apps; se os alertas chegarem atrasados, libere o app para rodar sem restrições nas configurações de bateria. Se você editou o settings.json à mão, o ccn doctor informa se os hooks dele continuam lá. O ccn upgrade atualiza para a versão mais recente.

08Perguntas frequentes