Voltar para o blog

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

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.
  • jq e curl.
  • 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

EventoTítuloCorpoNível
Resposta concluídaGemini finished · apiPrimeiros 300 caracteres da respostadefault
Permissão de ferramentaGemini needs approval · apiA mensagem de permissão do Gemini CLIhigh

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>&1 para ver a resposta do curl.
  • Verifique se os hooks estão ativados. Eles estão por padrão, mas hooksConfig.enabled: false nas 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ê.

Compartilhe este artigo