Como receber um aviso quando o Claude Code ou o Codex terminar

Como os agentes avisam que terminaram

As duas ferramentas conseguem rodar um comando seu na hora certa. Uma notificação é só isso: o Claude Code chama de hook, o Codex chama de notify. O que o comando fizer (tocar um som, mostrar um aviso, piscar a tela) acontece quando o agente para ou pede uma resposta.

Claude Code: a notificação que já vem nele

Quando o Claude Code termina, ou fica esperando uma permissão, ele mesmo pode mandar uma notificação na tela. A documentação da Anthropic diz que isso funciona sem configurar nada no Ghostty e no Kitty. No iTerm2, ative uma vez:

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

Usa o Claude Code dentro do tmux? Adicione set -g allow-passthrough on ao ~/.tmux.conf, senão a notificação nunca chega ao seu terminal. Você também pode escolher como o Claude Code avisa você (por exemplo, com o sino do terminal) nos ajustes de /config.

Fonte: documentação do Claude Code: configuração do terminal

Claude Code: um hook que toca um som

No Terminal da Apple, no VS Code ou em qualquer outro terminal, um hook resolve. Os hooks ficam em ~/.claude/settings.json (para todos os projetos) ou em .claude/settings.json (um projeto só). Dois eventos importam:

• Stop: o Claude terminou a resposta.
• Notification: o Claude precisa de você (um pedido de permissão, ou ele está esperando você responder).

Isto toca um som do macOS nos dois casos. Junte ao seu arquivo de ajustes (mantendo o que já estiver lá):

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

Prefere um aviso na tela? Use este comando no lugar (o mesmo do exemplo da Anthropic):

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

Digite /hooks no Claude Code para ver o que está configurado. Hooks novos valem para as sessões que você abrir depois de salvar. Os sons em /System/Library/Sounds/ são livres para usar: Glass, Ping, Pop, Purr, Submarine e outros.

Fontes: referência de hooks · guia de hooks

Codex: o ajuste notify

O Codex CLI roda um programa seu depois de cada turno, definido com notify no ~/.codex/config.toml. O Codex acrescenta uma descrição do turno em JSON como último argumento (o type dela é agent-turn-complete), que um simples comando de som pode ignorar:

notify = ["sh", "-c", "afplay /System/Library/Sounds/Glass.aiff"]

notify é uma chave de nível superior: coloque acima de qualquer [section] do arquivo. O Codex também tem notificações próprias na interface do terminal (notifications em [tui]), que usam a notificação ou o sino do próprio terminal; se aparece um aviso na tela ou não depende do seu terminal.

O notify do Codex dispara quando um turno termina. Ele não tem um evento separado de “precisa da sua aprovação”, como o hook Notification do Claude Code.

Fonte: documentação do Codex: configuração avançada

Agent Alerts do Clacky: o mesmo, sem configuração

Se você prefere não editar JSON e TOML, o Clacky (um app da barra de menus do Mac) tem o Agent Alerts. Ele usa os mesmos hooks de cima, então nada fica olhando sua tela nem lendo seu terminal:

1. Abra o painel do Clacky → Agent Alerts.
2. Ao lado do Claude Code ou do Codex, clique em Set Up…. O Clacky mostra exatamente as linhas que vai adicionar; clique em Add Hooks. Ele guarda um backup do seu arquivo ao lado dele (settings.json.clacky-backup).
3. Clique em Send a Test Alert para ouvir os dois sons.

O que você ganha:

• Um som diferente para pronto (um acorde subindo) e para precisa de você (dois toques e uma pergunta), com cinco vozes para escolher por agente.
• Um brilho suave na borda da tela opcional, por mais ou menos um segundo. Dá para clicar através dele e ele nunca aparece nas gravações.
• Quiet when it’s in front (em silêncio enquanto o terminal do agente é o app ativo) e Quiet during calls (em silêncio enquanto o microfone está em uso), os dois ligados por padrão.
• Um ponto por sessão na barra de menus: trabalhando, esperando ou pronto. Clique num deles para trazer o terminal para a frente.
• Keep Awake → Until My Agent Is Done (manter ativo até o agente terminar), para uma tarefa longa não parar porque o Mac dormiu.

O Claude Code funciona em qualquer terminal e na aba Code do app do Claude. O Codex funciona com a CLI e ganha o som de pronto (o Codex não manda nenhum evento de “precisa de você”). Se a sua configuração do Codex já tem uma linha notify, o Clacky não mexe nela e avisa você, em vez de substituir. Remove… tira só as linhas do Clacky.

Se nada acontecer

• Reinicie a sessão. Os hooks são lidos quando a sessão começa, então uma que já estava rodando não vai avisar.
• Confira se o arquivo é válido. Uma vírgula faltando no settings.json trava todos os hooks. Cole ele em qualquer validador de JSON.
• Teste o comando sozinho. Rode afplay /System/Library/Sounds/Glass.aiff no Terminal. Sem som? Confira o dispositivo de saída e o volume.
• Os avisos não aparecem? Confira Ajustes do Sistema → Notificações para o seu terminal (ou o Editor de Scripts, no caso do osascript), e os modos de Foco.
• Dois sons ao mesmo tempo? Você tem duas configurações (por exemplo, seu próprio hook e o do Clacky). Fique com uma.