Torna al blog

Notifiche push per Gemini CLI: finito, o in attesa di approvazione

Notifiche push per Gemini CLI: finito, o in attesa di approvazione

Gemini CLI può avvisarti da solo, ma solo nel terminale: attiva general.enableNotifications e invia una notifica desktop o un suono quando ha finito o ha bisogno di te. Questo aiuta quando sei davanti al computer e il terminale è in un'altra scheda. Non serve a nulla quando non sei davanti al computer.

Gli hook colmano questo divario. Dalla v0.26 sono attivi per impostazione predefinita, e due degli eventi sono esattamente ciò per cui serve una notifica push sul telefono:

  • AfterAgent: Gemini ha terminato il suo turno. Il payload include la risposta.
  • Notification: Gemini chiede il permesso di eseguire uno strumento.

Questa guida invia entrambi sul tuo telefono tramite Pocket Alert.

Una nota su quale Gemini CLI

Dal 18 giugno 2026, la documentazione di Google indica che Gemini CLI è stato sostituito da Antigravity CLI per il piano gratuito e i piani Google One. Gemini CLI prosegue con una chiave API Gemini a pagamento, Vertex AI o accesso aziendale, ed è questo il caso trattato in questa guida. Se usi Antigravity CLI, consulta la sua documentazione per gli hook.

Cosa ti serve

  • Gemini CLI v0.26 o successiva.
  • jq e curl.
  • Un account Pocket Alert, una chiave API da API Keys e l'app sul telefono. Il piano gratuito è sufficiente.

Salva la chiave in un file. Gemini CLI può rimuovere le variabili d'ambiente il cui nome contiene KEY o TOKEN prima di eseguire gli hook, quando la redazione dell'ambiente è attiva o quando viene eseguito in GitHub Actions, e una chiave letta da file non viene interessata:

mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key

Passo 1. Lo script dell'hook

Gemini CLI invia a ogni hook un oggetto JSON su stdin con hook_event_name e cwd. AfterAgent aggiunge prompt_response; Notification aggiunge notification_type e message. Salva come ~/.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

Gemini CLI interpreta lo stdout di un hook come JSON, quindi lo script stampa {} e nient'altro; l'output di curl va in /dev/null. Un codice di uscita 2 da un hook AfterAgent rifiuterebbe la risposta e farebbe riprovare Gemini, quindi lo script non lo restituisce mai.

Oppure con la CLI di Pocket Alert

Con la CLI di Pocket Alert 2.0 o successiva installata, il blocco curl si riduce a un solo comando. La CLI effettua da sola l'escape del testo e prende la chiave da pocketalert auth, il che evita anche la rimozione delle variabili descritta sopra:

pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true

Mantieni -t e -m invece degli argomenti posizionali: una risposta che inizia con un trattino, come un elenco Markdown, verrebbe altrimenti letta come opzione.

Passo 2. Registra gli hook

Aggiungi un blocco hooks a ~/.gemini/settings.json, unendolo a quanto già presente:

{
  "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
          }
        ]
      }
    ]
  }
}

Sostituisci /Users/you con la tua home directory. Qui timeout è espresso in millisecondi, a differenza di alcuni altri agenti. Per un singolo progetto, inserisci lo stesso blocco in .gemini/settings.json nel repository; Gemini CLI esegue gli hook di progetto solo in una cartella attendibile.

Passo 3. Testalo

Esegui prima lo script con un evento finto:

echo '{"hook_event_name":"AfterAgent","cwd":"/tmp/demo","prompt_response":"Hook test"}' \
  | ~/.gemini/hooks/pocketalert.sh

Poi avvia Gemini CLI e assegnagli un compito che termina con una chiamata a uno strumento che richiede approvazione, ad esempio "crea un file chiamato notes.txt". Ricevi Gemini richiede approvazione mentre attende, e Gemini finito dopo che lo autorizzi e il turno termina.

Cosa arriva sul telefono

EventoTitoloCorpoLivello
Turno terminatoGemini finito · apiPrimi 300 caratteri della rispostadefault
Permesso strumentoGemini richiede approvazione · apiIl messaggio di permesso di Gemini CLIhigh

high arriva come urgente su iPhone, quindi le richieste di approvazione passano attraverso Full immersion. Ogni notifica push resta disponibile nell'app e nella dashboard web.

Oppure lascia che Gemini la invii tramite MCP

Con il server MCP di Pocket Alert, Gemini può inviare notifiche push che scrive da solo, nei momenti che indichi tu. Aggiungilo da riga di comando:

gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer $POCKETALERT_API_KEY' \
  pocketalert https://mcp.pocketalert.app/mcp

Le virgolette singole fanno sì che $POCKETALERT_API_KEY resti una variabile nel file delle impostazioni invece di scrivere la chiave al suo interno; Gemini CLI la espande al momento della connessione, quindi esporta la variabile nella shell che avvia gemini. Senza --scope user il server viene aggiunto solo al progetto corrente.

Il risultato in ~/.gemini/settings.json:

{
  "mcpServers": {
    "pocketalert": {
      "url": "https://mcp.pocketalert.app/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $POCKETALERT_API_KEY" }
    }
  }
}

Esegui /mcp dentro Gemini CLI per vedere il server e i suoi strumenti. Poi un prompt come "esegui la migrazione e mandami il numero di righe quando finisce" termina con una chiamata a create_message.

Se non arriva nulla

  • Esegui il comando di test. Se non arriva la notifica push, il problema è la chiave o la rete; rimuovi >/dev/null 2>&1 per vedere la risposta di curl.
  • Controlla che gli hook siano attivi. Lo sono per impostazione predefinita, ma hooksConfig.enabled: false nelle impostazioni li disattiva.
  • Controlla il percorso in command: deve essere assoluto e lo script deve essere eseguibile.
  • Controlla lo stdout. Qualsiasi cosa diversa da JSON sullo stdout fa sì che Gemini CLI ignori il risultato dell'hook. Assicurati che nessun altro comando nello script stampi qualcosa.

FAQ

Qual è la differenza rispetto a general.enableNotifications?

Quella impostazione invia notifiche di terminale sul tuo computer quando Gemini ha bisogno di te o termina. Gli hook eseguono un comando qualsiasi, quindi possono raggiungere il telefono, conservare uno storico e usare livelli di priorità.

Posso approvare la chiamata allo strumento dal telefono?

Non con questo script: ti avvisa che Gemini è in attesa, e l'approvazione avviene nel terminale. Un hook BeforeTool può bloccare una chiamata a uno strumento, quindi un punto di approvazione è possibile con un endpoint che il telefono richiama; Notifiche human-in-the-loop mostra lo schema.

Funziona in GitHub Actions?

Sì, e l'approccio con il file della chiave qui è importante: in GitHub Actions, Gemini CLI rimuove dall'ambiente dell'hook le variabili con KEY o TOKEN nel nome. Scrivi la chiave da un secret in un file in un passo precedente.

È gratuito?

Gli hook fanno parte di Gemini CLI, e il piano gratuito di Pocket Alert copre 50 messaggi al giorno su un dispositivo. Gemini stesso richiede una chiave API a pagamento o un accesso aziendale per la CLI, come indicato sopra.

Ottieni una chiave API, aggiungi gli hook e lascia che Gemini ti trovi quando ha bisogno di te.

Condividi questo articolo