# Notifiche Codex CLI: una push quando il task è finito

> Ricevi una notifica push sul telefono quando OpenAI Codex CLI termina un turno o chiede un'approvazione. Hook di Codex con Pocket Alert, e l'impostazione notify più vecchia come alternativa.

*14.10.2026*

<!-- source: https://pocketalert.app/it/blog/codex-notifications -->

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](/account/apikeys) e l'[app](/get-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:

```bash
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`:

```bash
#!/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
```

```bash
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](/tools/cli) 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ù:

```bash
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`:

```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:

```text
> 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:

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

## Cosa arriva sul telefono

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento</th><th>Titolo</th><th>Corpo</th><th>Livello</th></tr></thead>
<tbody>
<tr><th>Turno terminato</th><td>Codex finito · api</td><td>Primi 300 caratteri dell'ultima risposta</td><td>default</td></tr>
<tr><th>Approvazione necessaria</th><td>Codex richiede approvazione · api</td><td>Vuole eseguire Bash</td><td>high</td></tr>
</tbody>
</table>
</div>

`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:

```bash
#!/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
```

```toml
# ~/.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](/tools/mcp) a `~/.codex/config.toml`:

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

oppure dalla riga di comando:

```bash
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](/blog/human-in-the-loop-notifications) 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](/signup), aggiungi l'hook e smetti di controllare il terminale.
