No macOS, o Claude Code já envia uma notificação na área de trabalho no Ghostty, no Kitty e no iTerm2 (no iTerm2 é preciso ativar as configurações de alerta), mas o Apple Terminal e a maioria dos outros terminais não recebem nada. Para ter notificação em qualquer terminal, adicione ao ~/.claude/settings.json um hook Notification que execute osascript -e 'display notification ...', e um hook Stop se você também quiser saber na hora em que o Claude terminar. Permita notificações para o Editor de Scripts nos Ajustes do Sistema, senão o comando osascript falha sem dar nenhum aviso.
01O que o Claude Code faz por conta própria
O Claude Code dispara um evento de notificação quando termina uma tarefa ou fica esperando uma permissão e parece que você não está no terminal. O que aparece depende do terminal, segundo o guia de terminal da Anthropic:
No iTerm2, abra Settings > Profiles > Terminal, marque Notification Center Alerts, clique em Filter Alerts e ative Send escape sequence-generated alerts. Confira também se o iTerm2 tem permissão para enviar notificações em Ajustes do Sistema > Notificações.
No Apple Terminal, dá pelo menos para ter um som. Defina "preferredNotifChannel": "terminal_bell" no ~/.claude/settings.json e ative Sino audível em Ajustes > Perfis > Avançado. O guia do sino do terminal explica esse caminho em detalhes.
O alerta nativo tem limitações. Ele só dispara quando o Claude Code acha que você saiu, só avisa que algo aconteceu e nunca sai do computador.
02Um hook de notificação com osascript
Um hook funciona em qualquer terminal, inclusive nos terminais de IDE. Este é o exemplo para macOS do guia de hooks da Anthropic. Adicione ao ~/.claude/settings.json, mantendo as outras chaves que você já tem:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}Digite /hooks no Claude Code para confirmar que ele aparece em Notification.
A permissão do Editor de Scripts
O osascript publica as notificações como Editor de Scripts. Se o Editor de Scripts não tiver permissão de notificação, o comando falha silenciosamente e o macOS não pergunta nada. Execute isto uma vez no Terminal:
osascript -e 'display notification "test"'Na primeira vez não aparece nada. Abra Ajustes do Sistema > Notificações, procure Editor de Scripts e ative Permitir Notificações. Execute o comando de novo e a notificação de teste deve aparecer.
Quando dispara
O matcher vazio dispara para todos os tipos de notificação. Os dois que mais importam são permission_prompt (o Claude esperou uns seis segundos por uma aprovação e você não digitou nada) e idle_prompt (o Claude terminou há uns 60 segundos e você não digitou nada desde então). O guia do Notification hook lista todos os tipos e quando cada um dispara.
03Saiba na hora em que o Claude terminar
O idle_prompt espera um minuto. Para ser avisado na hora, adicione um hook Stop, que roda quando o Claude encerra a vez dele. O Stop não usa matcher:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\" sound name \"Glass\"'"
}
]
}
]
}
}O sound name aceita qualquer som de /System/Library/Sounds, como Glass, Ping ou Hero. Se você só quer um som, use afplay /System/Library/Sounds/Glass.aiff como comando. Mais sobre esse evento no guia do Stop hook.
04Mostre a mensagem real
Os hooks recebem JSON pela entrada padrão. A entrada do Notification tem um campo message, como "Claude needs your permission". Um pequeno script pode colocar esse texto na notificação. Salve isto como ~/.claude/hooks/notify-mac.sh:
#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
osascript -e 'on run argv' \
-e 'display notification (item 1 of argv) with title "Claude Code"' \
-e 'end run' "$msg"Como o texto é passado como argumento, e não dentro da string do AppleScript, aspas na mensagem não quebram o comando. Torne o script executável com chmod +x ~/.claude/hooks/notify-mac.sh e defina o comando do hook como ~/.claude/hooks/notify-mac.sh. O script precisa do jq (brew install jq se jq --version falhar).
05terminal-notifier: clique para voltar ao terminal
Ao clicar numa notificação do osascript, abre o Editor de Scripts, que não é para onde você quer ir. O terminal-notifier permite escolher qual app vem para a frente:
brew install terminal-notifier
terminal-notifier -title "Claude Code" -message "Claude has finished" -sound default -activate com.googlecode.iterm2Use com.apple.Terminal para o Apple Terminal, ou o bundle ID do seu editor. O mesmo comando vai no campo command do hook. Na primeira vez, permita notificações para o terminal-notifier nos Ajustes do Sistema.
06Foco e Não Perturbe
Todas essas são notificações comuns do macOS, então um modo de Foco pode escondê-las. Se elas somem em certos horários, confira Ajustes do Sistema > Foco e permita o app que as publica (Editor de Scripts, terminal-notifier ou seu terminal). Para notificações que respeitem seus próprios horários, veja horário silencioso e Não Perturbe.
07Onde o Claude Code Notifier se encaixa
Os hooks acima resolvem bem se você fica no Mac e só quer um toque. Eles deixam de ser suficientes quando você se afasta, porque uma notificação no Mac não chega até você na cozinha e não consegue responder ao Claude.
O Claude Code Notifier é uma ferramenta independente (feita pela TouchTap, não pela Anthropic) construída sobre os mesmos hooks. A ferramenta de linha de comando gratuita, ccn, roda no Mac, no Windows e no Linux. Instale no seu Mac com:
curl -fsSL https://claudecodenotifier.com/install.sh | shou com Homebrew: brew trust --formula touch-tap/tap/ccn && brew install touch-tap/tap/ccn. Ele adiciona as entradas de hook ao ~/.claude/settings.json, não mexe no resto do arquivo e guarda um backup. A partir daí, mostra uma notificação do macOS quando o Claude termina, precisa de permissão ou faz uma pergunta, sem precisar de rede nem de celular.
Se você parear um iPhone ou um celular Android, os mesmos eventos chegam como notificações push, e você pode permitir ou negar uma permissão, escolher uma resposta para a pergunta do Claude ou enviar a próxima instrução pelo celular. Se você digitou algo nos últimos 30 segundos, o terminal pergunta normalmente e nada fica esperando no celular. Veja como parear um celular e a página do ccn. Os apps de celular exigem assinatura ou compra vitalícia; veja os preços.
Se você adicionar o ccn, remova seus próprios hooks com osascript, senão vai ver duas notificações para cada evento. Também existe um app antigo de barra de menus para Mac; não o use junto com o ccn no mesmo Mac.
08Perguntas frequentes
Por que meu hook com osascript não mostra nada?
Na maioria das vezes, o Script Editor não tem permissão de notificação, então o macOS descarta a notificação sem dar erro. Rode osascript -e 'display notification "test"' uma vez e depois permita o Script Editor em Ajustes do Sistema > Notificações. Se ainda não funcionar, confira se nenhum modo de Foco está ativo e se o /hooks lista o seu hook.
O Claude Code envia notificações no macOS sem nenhuma configuração?
Sim, no Ghostty e no Kitty, e no iTerm2 depois que os alertas da Central de Notificações estiverem ativados. O Terminal da Apple e os terminais de IDE não recebem notificação na área de trabalho por padrão, então use um hook ou o ccn nesses casos.
Como recebo uma notificação assim que o Claude termina, e não um minuto depois?
Use um hook Stop. A notificação idle_prompt só dispara cerca de 60 segundos depois que o Claude termina, e só se você não tiver digitado nada, enquanto o Stop roda ao fim de cada turno.
Posso ouvir um som em vez de ver um banner?
Sim. Use afplay /System/Library/Sounds/Glass.aiff como comando do hook, ou adicione sound name "Glass" ao comando osascript para ter os dois.
Posso aprovar uma permissão pela notificação do macOS?
Não com osascript ou terminal-notifier: eles só exibem texto. Responder a uma permissão a partir de um hook exige o evento PermissionRequest; veja como responder a pedidos de permissão com um hook ou aprove pelo celular com o Claude Code Notifier.