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 comeStop,PermissionRequest,PreToolUseeSessionEnd. Il comando riceve l'evento come JSON su stdin. notify, l'impostazione più vecchia inconfig.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.
jqecurl.- 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
| Evento | Titolo | Corpo | Livello |
|---|---|---|---|
| Turno terminato | Codex finito · api | Primi 300 caratteri dell'ultima risposta | default |
| Approvazione necessaria | Codex richiede approvazione · api | Vuole eseguire Bash | high |
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>&1per vedere l'errore di curl.401significa che la chiave è sbagliata. - Controlla che gli hook siano attendibili. Apri
/hooksin Codex; gli hook non attendibili o modificati vengono saltati. - Controlla che il progetto sia attendibile se hai messo
hooks.jsonnel repository. - Controlla che
jqsia 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.