Torna al blog

Notifiche Codex CLI: una push quando il task è finito

Notifiche Codex CLI: una push quando il task è finito

Codex CLI ti avvisa già quando ha finito, a patto che tu stia guardando il terminale. Le sue notifiche integrate sono codici di escape del terminale: un banner sul desktop se il tuo terminale li supporta, un suono se non li supporta. Nessuna delle due ti segue in cucina.

Codex può anche eseguire i tuoi comandi in determinati punti del suo ciclo di vita, ed è tutto ciò che serve per una notifica push sul telefono. Questa guida ne invia una quando Codex termina un turno e un'altra quando si ferma per chiedere un'approvazione.

Due modi in cui Codex esegue il tuo comando

  • Hook, il meccanismo attuale. Si configura in hooks.json, è attivo di default, con eventi come Stop, PermissionRequest, PreToolUse e SessionEnd. Il comando riceve l'evento come JSON su stdin.
  • notify, l'impostazione più vecchia in config.toml. Si attiva su un solo evento, agent-turn-complete, e passa il JSON come ultimo argomento da riga di comando. Funziona ancora, ma il codice sorgente di Codex lo segna come legacy.

Usa gli hook. La versione con notify è alla fine, per le configurazioni più datate.

Cosa ti serve

  • Codex CLI, una versione recente con supporto agli hook.
  • 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 API in un file leggibile solo da te, così non finisce nella cronologia della shell né nelle variabili d'ambiente:

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

Passo 1. Lo script dell'hook

Salvalo come ~/.codex/hooks/pocketalert.sh:

#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Codex finished · $project"
    message=$(jq -r '.last_assistant_message // "Turn complete"' <<<"$payload")
    level=default ;;
  PermissionRequest)
    title="Codex needs approval · $project"
    message=$(jq -r '"Wants to run " + (.tool_name // "a tool")' <<<"$payload")
    level=high ;;
  *) 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 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

exit 0
chmod +x ~/.codex/hooks/pocketalert.sh

Codex è rigoroso con l'output degli hook. Per Stop si aspetta o nulla o JSON su stdout, e il codice di uscita 2 gli dice di continuare invece di fermarsi. Per questo tutto l'output di curl va in /dev/null e lo script termina sempre con exit 0.

Gli hook PermissionRequest possono anche approvare o negare per conto di Codex. Questo non fa né l'uno né l'altro: non stampa nulla, quindi Codex mostra il normale prompt di approvazione e tu ricevi una push che ti dice che sta aspettando.

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 gestisce da sola l'escape del testo e prende la chiave da pocketalert auth, quindi il file della chiave non serve più:

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

Crea ~/.codex/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ]
  }
}

Il file nella tua directory home si applica ovunque. Un .codex/hooks.json dentro un repository si applica a quel progetto, ma solo dopo che hai contrassegnato il progetto come attendibile.

Gli hook sono attivi di default. Se in passato li hai disattivati, rimuovi hooks = false dalla tabella [features] in ~/.codex/config.toml.

Codex esegue solo gli hook che hai verificato e considerato attendibili. Alla prossima partenza ti avvisa che i nuovi hook richiedono una verifica: apri /hooks, controlla le due voci e considerale attendibili. Se le modifichi in seguito, Codex le salta finché non le consideri di nuovo attendibili.

Passo 3. Provalo

Avvia Codex in un progetto qualsiasi e dagli un task breve:

> Summarise README.md in one sentence.

Quando il turno finisce, il telefono mostra Codex finito · il-tuo-progetto con il riassunto. Chiedigli di eseguire un comando che richiede approvazione, e arriva una seconda push, Codex richiede approvazione, con priorità alta.

Per testare lo script senza Codex:

echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | ~/.codex/hooks/pocketalert.sh

Cosa arriva sul telefono

EventoTitoloCorpoLivello
Turno terminatoCodex finito · apiPrimi 300 caratteri dell'ultima rispostadefault
Approvazione necessariaCodex richiede approvazione · apiVuole eseguire Bashhigh

high viene consegnata come time-sensitive su iPhone, quindi la push di approvazione passa anche con Full immersion, mentre le push ordinarie "finito" restano silenziose. Entrambe restano nella cronologia dell'app e nella dashboard web.

Il metodo più vecchio: notify

Se la tua versione di Codex è precedente agli hook, o usi già notify, funziona con alcune modifiche. Codex passa l'evento come ultimo argomento invece che su stdin, usa chiavi in kebab-case e segnala solo i turni terminati:

#!/usr/bin/env bash
event="${@: -1}"
[ "$(jq -r '.type' <<<"$event")" = "agent-turn-complete" ] || exit 0

jq -n --arg m "$(jq -r '."last-assistant-message" // "Turn complete"' <<<"$event" | cut -c1-300)" \
  '{title: "Codex finished", message: $m}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]

notify non ha un evento di approvazione, quindi usa gli hook se vuoi sapere quando Codex è bloccato.

Oppure lascia che Codex lo invii tramite MCP

Gli hook si attivano su eventi fissi. Per lasciare che Codex decida cosa comunicarti, aggiungi il server MCP di Pocket Alert a ~/.codex/config.toml:

[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"

oppure dalla riga di comando:

codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
  --bearer-token-env-var POCKETALERT_API_KEY

Esporta POCKETALERT_API_KEY nella shell che avvia Codex. Poi un prompt del tipo "esegui la suite di test e mandami le failure" termina con Codex che chiama create_message con un riassunto scritto da lui. Lo strumento accetta anche level e actions.

Se non arriva niente

  • Esegui il comando di test. Se funziona lì, il problema è nella registrazione degli hook; se non funziona, rimuovi >/dev/null 2>&1 per vedere l'errore di curl. 401 significa che la chiave è sbagliata.
  • Controlla che gli hook siano attendibili. Apri /hooks in Codex; gli hook non attendibili o modificati vengono saltati.
  • Controlla che il progetto sia attendibile se hai messo hooks.json nel repository.
  • Controlla che jq sia nel PATH che Codex vede. I comandi degli hook girano con l'ambiente di Codex e la directory di lavoro della sessione.
  • Controlla il limite giornaliero. Il piano gratuito invia 50 messaggi al giorno, e Stop si attiva dopo ogni turno.

FAQ

E [tui] notifications?

È la notifica da terminale integrata di Codex. È attiva di default e può coprire sia i turni terminati sia le richieste di approvazione, ma compare sul computer, tramite il terminale. Una push raggiunge il telefono e mantiene una cronologia.

Funziona anche nell'estensione IDE di Codex?

L'estensione esegue l'agente Codex sulla tua macchina con la stessa configurazione in ~/.codex, quindi configura e verifica prima gli hook nella CLI. I task cloud di Codex girano sui server di OpenAI e non eseguono i tuoi hook locali.

Posso approvare dal telefono?

Non con questo script: si limita a dirti che Codex sta aspettando. Un hook PermissionRequest può restituire una decisione di consenso o di rifiuto, quindi puoi costruire approvazioni sopra di esso con un endpoint che il telefono chiama. Notifiche human-in-the-loop mostra il pattern.

È gratis?

Sì. Gli hook sono integrati in Codex, e il piano gratuito di Pocket Alert copre 50 messaggi al giorno su un dispositivo.

Ottieni una chiave API, aggiungi l'hook e smetti di controllare il terminale.

Condividi questo articolo