# Notifiche push per Cursor: un avviso quando l'agente finisce

> Ricevi una notifica push sul telefono quando un agente Cursor finisce, fallisce o ha qualcosa da dirti. Un hook stop per ogni esecuzione, più il server MCP di Pocket Alert per i messaggi che l'agente scrive da solo.

*12.10.2026*

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

L'agente di Cursor può rifattorizzare un modulo mentre tu prepari il caffè, ma per una normale esecuzione locale Cursor ti avvisa che ha finito solo sul computer: con un suono, o con una notifica di sistema se le hai attivate. L'app iOS di Cursor invia una notifica push quando un agente completa un turno, ma solo per gli agenti cloud e per le sessioni che passi con Remote Control, con un piano a pagamento e un iPhone; per Android è previsto ma non ancora disponibile.

Se vuoi una notifica push sul telefono quando un'esecuzione locale dell'agente termina, Cursor ti offre due modi per inviarla:

- **Un hook `stop`.** Cursor esegue il tuo script ogni volta che il ciclo dell'agente termina, che sia stato completato, interrotto o che abbia generato un errore. Affidabile e sempre uguale.
- **Uno strumento MCP.** Aggiungi il server MCP di Pocket Alert e l'agente può inviarti una notifica push ogni volta che glielo chiedi, con un messaggio che scrive lui.

Questa guida configura entrambi. Ognuno richiede qualche minuto.

## Cosa ti serve

- Cursor 1.7 o successivo; gli hook sono arrivati con la 1.7.
- `jq` e `curl` per l'hook.
- Un account Pocket Alert, una chiave API da [API Keys](/account/apikeys) e l'[app](/get-app) sul telefono. Il piano gratuito basta.

Cursor avviato dal Dock non legge il tuo `.zshrc`, quindi le variabili d'ambiente esportate lì non sono visibili. Conserva la chiave in un file:

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

## Opzione 1. Un hook stop per ogni esecuzione

### Lo script

Cursor passa all'hook un oggetto JSON su stdin. Per `stop` include `status` (`completed`, `aborted` o `error`) e `workspace_roots`, le cartelle aperte nella finestra. Salva questo file come `~/.cursor/hooks/pocketalert.sh`:

```bash
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.workspace_roots[0] // "cursor"' <<<"$payload")")
status=$(jq -r '.status // "completed"' <<<"$payload")

case "$status" in
  completed) title="Cursor finished · $project"; level=default ;;
  error)     title="Cursor hit an error · $project"; level=high ;;
  *)         echo '{}'; exit 0 ;;
esac

jq -n --arg t "$title" --arg m "Agent run $status" --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 '{}'
```

```bash
chmod +x ~/.cursor/hooks/pocketalert.sh
```

Le esecuzioni interrotte vengono saltate di proposito: se hai premuto stop, lo sai già. Lo script stampa `{}` perché un hook `stop` può restituire un `followup_message` che Cursor rimanda all'agente come tuo prossimo prompt; un oggetto vuoto significa "nient'altro da aggiungere".

### 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 comando. La CLI gestisce da sola l'escape del testo e prende la chiave da `pocketalert auth`:

```bash
pocketalert send -t "$title" -m "Agent run $status" -l "$level" -q >/dev/null 2>&1 || true
```

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

### Registralo

Crea `~/.cursor/hooks.json`:

```json
{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": "/Users/you/.cursor/hooks/pocketalert.sh", "timeout": 10 }
    ]
  }
}
```

Usa il percorso assoluto dello script; sostituisci `/Users/you` con la tua cartella home. Il file nella cartella home si applica a tutti i progetti. Per un solo progetto, mettilo in `.cursor/hooks.json` nel repository.

Cursor ricarica da solo `hooks.json` quando il file cambia. Assegna all'agente un piccolo compito e, al termine, sul telefono comparirà **Cursor finished · your-project**.

### Vuoi la risposta dell'agente nella notifica?

`stop` non include la risposta dell'agente, ma `afterAgentResponse` sì, nel campo `text`. Per inviare le prime righe della risposta invece del solo stato, registra uno script dello stesso tipo su `afterAgentResponse` e leggi `.text` da stdin. Viene eseguito dopo ogni risposta, quindi è più rumoroso; la maggior parte delle persone tiene `stop`.

## Opzione 2. Il server MCP

L'hook ti dice che un'esecuzione è terminata. Il server MCP permette all'agente di dirti cosa è successo. Aggiungi Pocket Alert a `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pocketalert": {
      "url": "https://mcp.pocketalert.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

La chiave viene scritta nel file per via del problema del Dock descritto sopra. Questo file sta nella cartella home, non in un repository. Se avvii Cursor da un terminale con la chiave esportata, funziona anche `"Bearer ${env:POCKETALERT_API_KEY}"`.

Apri la sezione MCP delle Impostazioni di Cursor, verifica che `pocketalert` mostri i suoi strumenti e chiedi:

```text
> Run the test suite. When it's done, push me the number of failures with Pocket Alert.
```

L'agente chiama `create_message` con un riepilogo che ha scritto lui. Può anche impostare `level`, così una suite fallita può arrivare come `high`, e allegare pulsanti di azione con un piano a pagamento.

Per farlo diventare un'abitudine invece di un'istruzione da ripetere a ogni prompt, aggiungi una regola di progetto:

```text
When a task takes more than a few minutes, finish by calling the pocketalert
create_message tool with a one-line summary. Use level "high" if anything failed.
```

## Quale usare

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th></th><th>Hook stop</th><th>Strumento MCP</th></tr></thead>
<tbody>
<tr><th>Si attiva</th><td>Ad ogni esecuzione, sempre</td><td>Quando l'agente decide di farlo</td></tr>
<tr><th>Messaggio</th><td>Stato: completed o error</td><td>Quello che scrive l'agente</td></tr>
<tr><th>Richiede</th><td>Uno script e <code>hooks.json</code></td><td>Un blocco in <code>mcp.json</code></td></tr>
<tr><th>Può fallire in silenzio</th><td>Solo se la rete è giù</td><td>Se il modello se ne dimentica</td></tr>
</tbody>
</table>
</div>

Usarli insieme è un buon punto di partenza: l'hook ti garantisce di sapere di ogni esecuzione, lo strumento MCP ti dà il contenuto quando conta.

## Approvazioni

Cursor non ha un hook per "l'agente sta aspettando un'approvazione". `beforeShellExecution` e `preToolUse` si attivano prima di ogni comando, inclusi quelli che Cursor esegue senza chiedere, quindi non possono dirti quando sei davvero necessario. Le notifiche desktop di Cursor e la sua app iOS coprono questo caso oggi.

Se vuoi che l'agente si fermi e chieda prima di un passaggio rischioso, dagli lo strumento MCP e una regola per inviare una push con i pulsanti Approva e Rifiuta; [Notifiche human-in-the-loop](/blog/human-in-the-loop-notifications) mostra come trasformarlo in un vero blocco e non in una richiesta gentile.

## Se non arriva nulla

- **Esegui lo script a mano:** `echo '{"status":"completed","workspace_roots":["/tmp/demo"]}' | ~/.cursor/hooks/pocketalert.sh`. Se non arriva nessuna push, rimuovi `>/dev/null 2>&1` per vedere l'errore di curl.
- **Riavvia Cursor** se l'hook continua a non partire. Di norma Cursor ricarica da solo `hooks.json` quando il file cambia.
- **Controlla il percorso** in `hooks.json`: deve essere assoluto e lo script deve essere eseguibile.
- **Per MCP, controlla la lista degli strumenti.** Un errore accanto al server nelle impostazioni MCP di Cursor di solito significa che la chiave è sbagliata o vuota.

## FAQ

### Cursor ha già le notifiche push integrate?

Sul computer sì: un suono di completamento e notifiche di sistema. Sul telefono, l'app iOS di Cursor invia una push quando un agente cloud, o una sessione che passi con Remote Control, completa un turno. Serve un piano a pagamento e un iPhone. Le normali esecuzioni locali restano sul computer, ed è ciò che copre la configurazione qui descritta.

### Funziona anche per gli agenti in background e cloud?

L'hook in `~/.cursor/hooks.json` viene eseguito solo sulla tua macchina, quindi copre gli agenti locali. Gli agenti cloud girano sui server di Cursor: eseguono gli hook di progetto dal `.cursor/hooks.json` del repository ma non gli hook utente, e il file con la chiave non è presente. Per questi, la via MCP funziona se l'agente ha il server configurato, oppure puoi usare l'app iOS di Cursor o l'integrazione con Slack.

### L'agente vede la mia chiave API?

Nella configurazione con hook, no: la chiave resta in un file che legge solo lo script. Nella configurazione MCP, la chiave si trova nella configurazione di Cursor e viene inviata al server MCP, non al modello.

### È gratuito?

Sì. Hook e MCP fanno parte di Cursor, e il piano gratuito di Pocket Alert copre 50 messaggi al giorno su un dispositivo.

[Ottieni una chiave API](/signup), aggiungi l'hook e lascia che Cursor ti avvisi quando ha finito.
