Notificações do Gemini CLI: receba um som ou alerta quando ele terminar ou precisar de você
O Gemini CLI fica tranquilamente parado em “Waiting for confirmation” enquanto você lê outra coisa. Ele pode avisar você. A configuração só vem desativada por padrão e, no Windows, se comporta de um jeito diferente do que a documentação sugere.
RESPOSTA CURTA
Defina "general": { "enableNotifications": true } em ~/.gemini/settings.json (ou /settings → General → Enable Notifications). A partir daí, o Gemini CLI avisa quando precisa de aprovação e quando uma sessão termina. No Windows Terminal e no terminal do VS Code, o modo automático só toca o sino do terminal; então, se você quer uma notificação de verdade na área de trabalho, experimente notificationMethod: "osc9". Para um som seu, adicione um hook Notification (dispara em prompts de permissão de ferramenta) e um hook AfterAgent (dispara quando um turno termina).
Antes de começar: qual Gemini CLI você tem
Um banner na documentação do Gemini CLI diz que, para usuários do nível gratuito e do Google One, o Gemini CLI foi substituído pelo Antigravity CLI em 18 de junho de 2026. Tudo abaixo trata do próprio Gemini CLI (o comando gemini e o ~/.gemini/settings.json). Se você migrou para o Antigravity, as configurações dele ficam em outro lugar.
Muita gente quer isso há muito tempo. O pedido de recurso de notificações sonoras no repositório do Gemini CLI (#4310) recebeu 74 votos positivos, e um mantenedor aumentou a prioridade “to reflect how many people care” (para refletir quantas pessoas se importam). Uma discussão posterior (#13313) resumiu assim: “I can never tell when it is done.” (Nunca sei quando ele terminou.)
Ative as notificações integradas
O Gemini CLI tem um recurso experimental de notificações. Ele vem desativado por padrão. Ative-o na CLI com /settings → General → Enable Notifications ou no seu arquivo de configuração:
Depois de ativado, o Gemini CLI avisa você em dois eventos:
- Ação necessária: o modelo está esperando sua entrada ou a aprovação de uma ferramenta.
- Sessão concluída: uma sessão terminou com sucesso.
Os títulos das notificações são “Gemini CLI needs your attention” e “Gemini CLI session complete”. O Gemini CLI não toca nenhum som por conta própria: ele envia ao terminal uma sequência de escape, e o terminal decide o que acontece.
Como a notificação chega até você (e por que o Windows é diferente)
Uma segunda configuração, general.notificationMethod, escolhe como o alerta é enviado. Os valores são auto (padrão), osc9, osc777 e bell.
A página de notificações diz que a CLI usa a sequência de escape OSC 9 e, como alternativa, o sino do terminal. O código-fonte é mais específico. No modo auto (packages/cli/src/utils/terminalNotifications.ts):
| Terminal | O que o auto envia |
|---|---|
| iTerm2 | OSC 9 (uma notificação na área de trabalho) |
| Windows Terminal, terminal do VS Code, Alacritty, Terminal da Apple | Apenas o sino (BEL) |
| Todos os outros terminais | OSC 777 |
Então, no Windows Terminal você recebe o sino, não uma notificação pop-up. O que o sino faz é uma configuração do Windows Terminal: bellStyle aceita all, audible, window, taskbar e none, e o padrão é audible. Com all, o Windows Terminal toca um som e faz o ícone da barra de tarefas piscar; você pode escolher o som com bellSound.
Se você quiser experimentar uma notificação de verdade na área de trabalho em vez do sino, force o método:
Se um terminal transforma OSC 9 em notificação do Windows depende da versão do terminal. Se nada aparecer, volte para auto ou bell e use bellStyle: "all". O sino é o caminho que o próprio código do Gemini CLI escolheu para o Windows Terminal.
Dentro do tmux ou do screen, o Gemini CLI envolve a sequência em um escape de passthrough para que ela ainda chegue ao terminal externo.
Seu próprio som com hooks
Se você quer um som específico, um pop-up ou uma mensagem no celular, use hooks. O Gemini CLI executa comandos de hook em pontos fixos e espera que terminem. Dois eventos importam aqui:
Notificationdispara quando a CLI emite um alerta do sistema. Hoje o único tipo éToolPermission(uma ferramenta está esperando sua aprovação). O hook não pode aprovar nem bloquear nada; ele é apenas informativo.AfterAgentdispara uma vez por turno, depois da resposta final do modelo. A própria página de boas práticas do Gemini o recomenda quando “you only need to check the final completion” (você só precisa verificar a conclusão final).
Os hooks vêm ativados por padrão (hooksConfig.enabled). Um hook imprime exatamente um objeto JSON no stdout e nada mais ({} serve quando você não tem nada a dizer). O código de saída 0 significa sucesso; 2 bloqueia (e só importa em eventos bloqueáveis); qualquer outro é um aviso, e a CLI segue em frente. O timeout padrão é de 60 segundos (timeout é em milissegundos).
Windows (PowerShell)
No Windows, o Gemini CLI executa comandos de hook com pwsh -NoProfile -Command ou com powershell.exe se o PowerShell 7 não estiver instalado. Salve este script como %USERPROFILE%\.gemini\hooks\ding.ps1:
Depois, aponte os dois eventos para ele:
-ExecutionPolicy Bypass evita a falha mais comum: o PowerShell se recusando a executar scripts. A documentação do Gemini sugere Set-ExecutionPolicy RemoteSigned -Scope CurrentUser como solução permanente.
macOS e Linux
Nos outros sistemas, os hooks rodam com bash -c. Um script de uma linha resolve:
Torne-o executável (chmod +x ~/.gemini/hooks/ding.sh) e use "command": "$HOME/.gemini/hooks/ding.sh" nos mesmos dois eventos.
Quer dois sons diferentes, um para “precisa de aprovação” e outro para “terminou”? Crie dois scripts. Um hook também pode ler o evento do stdin: a entrada de Notification traz notification_type, message e details, então você pode mostrar a solicitação real no seu pop-up.
Por que seu hook não roda
- Confira o
/hooks panel. Ele lista todos os hooks que o Gemini CLI carregou./hooks enable-allos reativa se tiverem sido desativados. - Pasta não confiável. Em uma pasta não confiável, o Gemini CLI ignora o
.gemini/settings.jsondo projeto, então os hooks de projeto não são carregados. Coloque os hooks de notificação nas suas configurações de usuário (~/.gemini/settings.json) para que funcionem em qualquer lugar. - Hooks alterados contam como novos. O Gemini CLI gera uma impressão digital dos hooks de projeto; se o nome ou o comando de um hook mudar, ele é tratado como um hook novo e não confiável.
- Outra coisa no stdout. Um
echoperdido ou um aviso do PowerShell antes do JSON quebra o parsing. Envie os logs para o stderr. - Matchers. Para
NotificationeAfterAgent, use"*"(ou uma string vazia) para corresponder a tudo. Eventos de ciclo de vida usam matchers de string exata; eventos de ferramenta usam expressões regulares.
Ou receba menos perguntas
As notificações ajudam você a responder mais rápido; você também pode reduzir a frequência com que o Gemini CLI precisa de você. general.defaultApprovalMode pode ser default (pergunta), auto_edit (edições são aprovadas, todo o resto pergunta) ou plan (somente leitura). Shift+Tab alterna entre eles. tools.allowed lista ferramentas que pulam a caixa de confirmação (por exemplo, run_shell_command(git)), e tools.confirmationRequired lista ferramentas que sempre precisam perguntar.
O modo YOLO (--yolo ou Ctrl+Y) aprova tudo e ativa o sandbox por padrão. Ele só pode ser ativado pela linha de comando, e security.disableYoloMode o desativa de vez se você compartilha a máquina.
Onde o Pet Island entra
Um bipe avisa que algo aconteceu; ele não diz em qual terminal nem o que o Gemini quer executar. O Pet Island coloca o Gemini CLI em uma pequena ilha no topo da sua tela, ao lado dos seus outros agentes: você vê quando ele está trabalhando, quando está esperando sua confirmação e quando terminou, com um clique para ir ao terminal certo.
Com o Gemini CLI, a confirmação em si continua acontecendo no Gemini. O Pet Island mostra a solicitação e leva você até lá, mas não aprova as ferramentas do Gemini por você. (As solicitações do Claude Code e do Codex, por outro lado, podem ser respondidas direto na ilha.)
PERGUNTAS FREQUENTES
O Gemini CLI tem notificações?
Sim, como um recurso experimental que vem desativado por padrão. Defina general.enableNotifications como true em ~/.gemini/settings.json ou use /settings → General → Enable Notifications.
Por que o Gemini CLI só apita no Windows?
No modo auto, o código do Gemini CLI envia apenas o sino do terminal para o Windows Terminal e o terminal do VS Code. A configuração bellStyle do Windows Terminal controla se esse sino toca um som, faz a barra de tarefas piscar ou as duas coisas.
Um hook do Gemini CLI pode aprovar uma ferramenta automaticamente?
O hook Notification, não. A documentação diz que ele não pode bloquear alertas nem conceder permissões. Para pré-aprovar ferramentas, use tools.allowed ou o mecanismo de políticas.
Qual hook dispara quando o Gemini CLI termina?
O AfterAgent. Ele dispara uma vez por turno, depois da resposta final do modelo.
Onde coloco os hooks para que funcionem em todos os projetos?
Nas suas configurações de usuário, ~/.gemini/settings.json. As configurações de projeto são ignoradas em pastas não confiáveis.
Fontes
Todas as configurações e comportamentos desta página foram conferidos com estas páginas em 26 de outubro de 2026. Os agentes mudam rápido; se algo não bater mais, vale o que diz a página oficial.
- Documentação do Gemini CLI: Notifications (experimental)
- Documentação do Gemini CLI: Hooks
- Documentação do Gemini CLI: Hooks reference
- Documentação do Gemini CLI: Writing hooks (exemplo em PowerShell)
- Documentação do Gemini CLI: Configuration reference
- Documentação do Gemini CLI: Trusted folders
- Código-fonte do Gemini CLI: terminalNotifications.ts
- Issue #4310 do Gemini CLI: notificações sonoras
- Discussão #13313 do Gemini CLI: ativar som quando o Gemini terminar
- Microsoft Learn: configurações de perfil do Windows Terminal (bellStyle, bellSound)
- Microsoft Learn: Console.Beep