Notificações push para o Gemini CLI: pronto, ou aguardando aprovação

O Gemini CLI consegue avisar você sozinho, mas só pelo terminal: ative general.enableNotifications e ele envia uma notificação na área de trabalho ou um sinal sonoro quando termina ou precisa de você. Isso ajuda quando você está no computador e o terminal está em outra aba. Não adianta nada quando você não está na frente do computador.
Os hooks fecham essa lacuna. Desde a v0.26 eles vêm ativados por padrão, e dois dos eventos são exatamente para isso que serve uma notificação push no celular:
- AfterAgent: o Gemini terminou sua resposta. O payload inclui o conteúdo da resposta.
- Notification: o Gemini está pedindo permissão para executar uma ferramenta.
Este guia envia os dois para o seu celular pelo Pocket Alert.
Uma nota sobre qual Gemini CLI
Desde 18 de junho de 2026, a documentação do Google informa que o Gemini CLI foi substituído pelo Antigravity CLI no plano gratuito e nos planos Google One. O Gemini CLI continua disponível com uma chave de API do Gemini paga, Vertex AI ou acesso empresarial, e é isso que este guia cobre. Se você usa o Antigravity CLI, consulte a documentação dele sobre hooks.
O que você precisa
- Gemini CLI v0.26 ou superior.
jqecurl.- Uma conta no Pocket Alert, uma chave de API em Chaves de API e o aplicativo no seu celular. O plano gratuito é suficiente.
Guarde a chave em um arquivo. O Gemini CLI pode remover variáveis de ambiente cujo nome contém KEY ou TOKEN antes de executar os hooks, quando a redação de variáveis de ambiente está ativada ou quando ele roda no GitHub Actions. Uma chave lida de um arquivo não é afetada:
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
Passo 1. O script do hook
O Gemini CLI envia para cada hook um objeto JSON pela entrada padrão (stdin), com hook_event_name e cwd. AfterAgent acrescenta prompt_response; Notification acrescenta notification_type e message. Salve como ~/.gemini/hooks/pocketalert.sh:
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")
case "$(jq -r '.hook_event_name' <<<"$payload")" in
AfterAgent)
title="Gemini finished · $project"
message=$(jq -r '.prompt_response // "Turn complete"' <<<"$payload")
level=default ;;
Notification)
title="Gemini needs approval · $project"
message=$(jq -r '.message // "Waiting for tool permission"' <<<"$payload")
level=high ;;
*) echo '{}'; exit 0 ;;
esac
jq -n --arg t "$title" --arg m "${message:0:300}" --arg l "$level" \
'{title: $t, message: $m, level: $l}' |
curl -sS --max-time 5 https://api.pocketalert.app/v1/messages \
-H "Token: $(cat ~/.config/pocketalert/key)" \
-H 'Content-Type: application/json' \
--data-binary @- >/dev/null 2>&1 || true
echo '{}'
chmod +x ~/.gemini/hooks/pocketalert.sh
O Gemini CLI interpreta a saída padrão (stdout) de um hook como JSON, então o script imprime {} e nada além disso; a saída do curl vai para /dev/null. Um código de saída 2 em um hook AfterAgent rejeitaria a resposta e faria o Gemini tentar de novo, por isso o script nunca o retorna.
Ou com o CLI do Pocket Alert
Com o CLI do Pocket Alert 2.0 ou superior instalado, o bloco do curl se reduz a um único comando. O CLI escapa o texto por conta própria e pega a chave de pocketalert auth, o que também contorna a remoção de variáveis descrita acima:
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
Use -t e -m em vez de argumentos posicionais: uma resposta que começa com hífen, como uma lista Markdown, seria lida como opção.
Passo 2. Registre os hooks
Adicione um bloco hooks em ~/.gemini/settings.json, mesclado com o que já existir:
{
"hooks": {
"AfterAgent": [
{
"matcher": "*",
"hooks": [
{
"name": "pocketalert-done",
"type": "command",
"command": "/Users/you/.gemini/hooks/pocketalert.sh",
"timeout": 10000
}
]
}
],
"Notification": [
{
"matcher": "*",
"hooks": [
{
"name": "pocketalert-approval",
"type": "command",
"command": "/Users/you/.gemini/hooks/pocketalert.sh",
"timeout": 10000
}
]
}
]
}
}
Substitua /Users/you pelo seu diretório pessoal. Aqui, timeout é em milissegundos, diferente de alguns outros agentes. Para um único projeto, coloque o mesmo bloco em .gemini/settings.json dentro do repositório; o Gemini CLI só executa hooks de projeto em uma pasta confiável.
Passo 3. Teste
Primeiro, execute o script com um evento falso:
echo '{"hook_event_name":"AfterAgent","cwd":"/tmp/demo","prompt_response":"Hook test"}' \
| ~/.gemini/hooks/pocketalert.sh
Depois, inicie o Gemini CLI e peça uma tarefa que termine em uma chamada de ferramenta que precise de aprovação, como "crie um arquivo chamado notes.txt". Você recebe Gemini needs approval enquanto ele espera, e Gemini finished depois que você autorizar e a resposta terminar.
O que chega no seu celular
| Evento | Título | Corpo | Nível |
|---|---|---|---|
| Resposta concluída | Gemini finished · api | Primeiros 300 caracteres da resposta | default |
| Permissão de ferramenta | Gemini needs approval · api | A mensagem de permissão do Gemini CLI | high |
high chega como urgente no iPhone, então pedidos de aprovação passam pelo Foco. Todas as notificações ficam no aplicativo e no painel web.
Ou deixe o Gemini enviar pelo MCP
Com o servidor MCP do Pocket Alert, o Gemini pode enviar notificações que ele mesmo escreve, nos momentos que você pedir. Adicione pela linha de comando:
gemini mcp add --scope user --transport http \
--header 'Authorization: Bearer $POCKETALERT_API_KEY' \
pocketalert https://mcp.pocketalert.app/mcp
As aspas simples mantêm $POCKETALERT_API_KEY como variável no arquivo de configurações, em vez de gravar a chave nele; o Gemini CLI a expande ao conectar, então exporte a variável no shell que inicia o gemini. Sem --scope user, o servidor é adicionado apenas ao projeto atual.
O resultado em ~/.gemini/settings.json:
{
"mcpServers": {
"pocketalert": {
"url": "https://mcp.pocketalert.app/mcp",
"type": "http",
"headers": { "Authorization": "Bearer $POCKETALERT_API_KEY" }
}
}
}
Execute /mcp dentro do Gemini CLI para ver o servidor e as ferramentas dele. Então, um pedido como "execute a migração e me envie a contagem de linhas quando terminar" termina com uma chamada de create_message.
Se nada chegar
- Execute o comando de teste. Se não houver push, o problema está na chave ou na rede; remova
>/dev/null 2>&1para ver a resposta do curl. - Verifique se os hooks estão ativados. Eles estão por padrão, mas
hooksConfig.enabled: falsenas configurações os desativa. - Confira o caminho em
command: ele precisa ser absoluto, e o script precisa ser executável. - Confira a saída padrão. Qualquer coisa que não seja JSON na saída padrão faz o Gemini CLI ignorar o resultado do hook. Garanta que nada mais no script imprima.
Perguntas frequentes
Qual é a diferença para general.enableNotifications?
Essa configuração envia notificações do terminal para o seu computador quando o Gemini precisa de você ou termina. Os hooks executam qualquer comando, então podem alcançar o seu celular, manter um histórico e usar níveis de prioridade.
Posso aprovar a chamada de ferramenta pelo celular?
Não com este script: ele avisa que o Gemini está esperando, e você aprova no terminal. Um hook BeforeTool pode bloquear uma chamada de ferramenta, então um portão de aprovação é possível com um endpoint que o seu celular chama; Notificações com humano no circuito mostra o padrão.
Funciona no GitHub Actions?
Sim, e a abordagem do arquivo de chave importa ali: no GitHub Actions, o Gemini CLI remove do ambiente do hook as variáveis com KEY ou TOKEN no nome. Grave a chave a partir de um segredo em um arquivo em uma etapa anterior.
É gratuito?
Os hooks fazem parte do Gemini CLI, e o plano gratuito do Pocket Alert cobre 50 mensagens por dia em um dispositivo. O próprio Gemini precisa de uma chave de API paga ou acesso empresarial para usar o CLI, como observado acima.
Crie uma chave de API, adicione os hooks e deixe o Gemini encontrar você quando precisar de você.