# Notifiche push per Claude Code: sai quando un task è finito

> Ricevi una notifica push sul telefono quando Claude Code finisce un task, aspetta un permesso o si ferma per un errore. Uno script di hook, tre eventi, nessun plugin.

*11.10.2026*

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

Claude Code è capace di lavorare da solo per venti minuti. Il problema è l'altra faccia di quei venti minuti: o stai lì a fissare il terminale, oppure te ne vai e torni scoprendo che aspetta un permesso dal terzo minuto.

Gli hook risolvono entrambe le cose. Claude Code esegue un comando shell in punti fissi del suo ciclo di vita, e tre di quei punti sono esattamente quelli che vuoi sul telefono:

- **Stop**: Claude ha finito di rispondere. Il task è completato, oppure ha una domanda.
- **Notification**: Claude ha bisogno di te. Un prompt per un permesso, oppure è fermo in attesa di un input.
- **StopFailure**: il turno si è chiuso per un errore API, per esempio un rate limit o un problema di fatturazione.

Questa guida collega tutti e tre gli eventi a Pocket Alert con un solo script. La configurazione richiede circa cinque minuti.

## Cosa ti serve

- Claude Code, una versione recente qualsiasi.
- `jq` e `curl`. Sono presenti nella maggior parte delle distribuzioni Linux; su macOS, `brew install jq`.
- Un account Pocket Alert e una chiave API da [Chiavi API](/account/apikeys). Il piano gratuito basta.
- L'app Pocket Alert sul tuo [iPhone o Android](/get-app), con l'accesso effettuato.

## Passo 1. Lo script dell'hook

Claude Code passa a ogni hook un oggetto JSON su stdin. I campi che ti servono sono `hook_event_name`, `cwd`, `last_assistant_message` su Stop, `message` su Notification ed `error` su StopFailure. Lo script trasforma tutto questo in una notifica push:

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

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Claude finished · $project"
    message=$(jq -r '.last_assistant_message // "Task complete"' <<<"$payload")
    level=default ;;
  Notification)
    title="Claude needs you · $project"
    message=$(jq -r '.message' <<<"$payload")
    level=high ;;
  StopFailure)
    title="Claude stopped · $project"
    message=$(jq -r '"API error: " + (.error // "unknown")' <<<"$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: $POCKETALERT_API_KEY" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null || true

exit 0
```

Salvalo come `~/.claude/hooks/pocketalert.sh` e rendilo eseguibile:

```bash
mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/pocketalert.sh
```

Due righe dello script contano più di quanto sembri:

- **`jq -n` costruisce il JSON.** L'ultimo messaggio di Claude è pieno di virgolette, backtick e a capo. Incollarlo a mano in una stringa JSON si rompe alla prima virgoletta; `jq` lo escapa correttamente.
- **`exit 0` alla fine, e `|| true` dopo curl.** Per un hook Stop, il codice di uscita 2 significa "non fermarti, continua". Un hook di notifica non deve mai bloccare Claude, nemmeno quando la rete è giù.

### 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 fa l'escape del testo da sola e prende la chiave da `POCKETALERT_API_KEY` (il blocco `env` qui sotto la imposta) oppure da `pocketalert auth`:

```bash
pocketalert send -t "$title" -m "${message:0:300}" -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.

## Passo 2. Registra gli hook

Aggiungi gli hook a `~/.claude/settings.json` così valgono per ogni progetto. Se il file ha già una chiave `hooks`, unisci queste voci a quella:

```json
{
  "env": {
    "POCKETALERT_API_KEY": "YOUR_API_KEY"
  },
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
    ],
    "StopFailure": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }]
      }
    ]
  }
}
```

Il blocco `env` passa la chiave API all'hook senza inserirla nel profilo della shell. Se esporti già `POCKETALERT_API_KEY` altrove, ometti il blocco.

Il `matcher` su Notification filtra per tipo di notifica. `permission_prompt` scatta quando un prompt di permesso è rimasto senza risposta per circa sei secondi, e `idle_prompt` circa un minuto dopo che Claude ha finito, se da allora non hai digitato nulla. In una sessione da terminale entrambi scattano solo quando sembri lontano dalla postazione, così non fanno vibrare il telefono mentre stai guardando. Stop non ha matcher: scatta ogni volta che Claude completa una risposta.

Per limitare gli hook a un solo repository, metti lo stesso blocco `hooks` in `.claude/settings.json` dentro quel repository, oppure in `.claude/settings.local.json` se vuoi tenerlo fuori da git.

## Passo 3. Provalo

Di norma Claude Code recepisce da solo le modifiche al file delle impostazioni (avvia una nuova sessione se `/hooks` non li elenca ancora). Dagli un compito semplice:

```text
> List the files in this directory and stop.
```

Quando Claude finisce, sul telefono compare **Claude ha finito · il-tuo-progetto** con l'inizio della sua risposta. Se non arriva nulla, esegui `/hooks` dentro Claude Code per vedere gli hook registrati.

Per testare lo script da solo, dagli in pasto un evento finto:

```bash
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | POCKETALERT_API_KEY=YOUR_API_KEY ~/.claude/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>Task completato</th><td>Claude ha finito · api</td><td>Primi 300 caratteri dell'ultima risposta di Claude</td><td>default</td></tr>
<tr><th>Prompt di permesso</th><td>Claude ha bisogno di te · api</td><td>Claude ha bisogno del tuo permesso</td><td>high</td></tr>
<tr><th>In attesa di input</th><td>Claude ha bisogno di te · api</td><td>Claude è in attesa del tuo input</td><td>high</td></tr>
<tr><th>Errore API</th><td>Claude si è fermato · api</td><td>Errore API: rate_limit</td><td>high</td></tr>
</tbody>
</table>
</div>

`high` arriva come time-sensitive su iPhone, quindi un prompt di permesso passa attraverso Full immersion mentre i messaggi di routine "finito" restano silenziosi. Ogni push resta anche nella cronologia dell'app e nella [dashboard web](/messages), così puoi riscorrere quello che Claude ha fatto durante la notte.

## Personalizzalo

**Solo quando sei lontano.** Stop scatta dopo ogni risposta, comprese quelle brevi che stai guardando. Aggiungi un interruttore in cima allo script:

```bash
[ -f ~/.claude/away ] || exit 0
```

Poi esegui `touch ~/.claude/away` quando lasci la scrivania e `rm ~/.claude/away` quando torni. I prompt di permesso conviene ricevarli comunque, quindi puoi mettere il controllo solo dentro il ramo `Stop)`.

**Raggruppa per progetto.** Crea un'applicazione per progetto in Pocket Alert e aggiungi `application_id` al JSON. L'app filtrerà così per progetto, e potrai assegnare a ciascuno un livello predefinito.

**Non bloccare Claude affatto.** Aggiungi `"async": true` accanto a `"type": "command"` e l'hook gira in background. Saltalo nelle esecuzioni headless (`claude -p`): gli hook in background vengono terminati alla fine della sessione, e la push potrebbe non partire mai.

**Riprendi dal telefono.** Con un piano a pagamento, un [pulsante di azione](https://info.pocketalert.app/features/action-buttons.html) di tipo `copy` con l'ID della sessione ti permette di copiare `claude --resume <id>` dal telefono e incollarlo quando torni alla postazione.

## Oppure lascia che Claude la invii tramite MCP

Gli hook sono deterministici: scattano che Claude se ne ricordi o no. L'altra strada è dare a Claude uno strumento di notifica e lasciare che decida quando usarlo. Aggiungi il [server MCP di Pocket Alert](/tools/mcp):

```bash
claude mcp add --transport http pocketalert https://mcp.pocketalert.app/mcp \
  --scope user --header "Authorization: Bearer YOUR_API_KEY"
```

Ora puoi dire "esegui la migrazione e mandami il numero di righe quando finisce", e Claude chiama `create_message` con un messaggio scritto per l'occasione. Lo strumento accetta anche `level` e `actions`, e `list_messages` permette a Claude di rileggere quello che ha inviato in precedenza.

Usa entrambi: gli hook per il "finito" e il "ho bisogno di te" garantiti, MCP per i messaggi con contenuto reale. Per le approvazioni prima di passaggi rischiosi, vedi [Notifiche human-in-the-loop](/blog/human-in-the-loop-notifications).

## Se non arriva nulla

- **Controlla la chiave.** Esegui il comando di test qui sopra. Un `401` da curl significa che la chiave API è sbagliata; rimuovi `>/dev/null` per vedere la risposta.
- **Controlla che gli hook siano caricati.** Esegui `/hooks`. Le modifiche al file delle impostazioni di norma vengono recepite in pochi secondi; se gli hook non compaiono, riavvia Claude Code.
- **Controlla che `jq` sia nel PATH** usato da Claude Code. Gli hook girano con l'ambiente di Claude, e un editor avviato dalla GUI potrebbe non vedere `/opt/homebrew/bin` di Homebrew.
- **Controlla il limite giornaliero.** Il piano gratuito invia 50 messaggi al giorno. Una sessione lunga con molti turni brevi può esaurirli; l'interruttore "away" qui sopra aiuta.

## FAQ

### Funziona con le estensioni per VS Code e JetBrains?

Sì. Le estensioni eseguono Claude Code sotto il cofano e leggono lo stesso `~/.claude/settings.json`, quindi anche lì gli hook scattano.

### Claude può vedere la chiave API?

Non nella conversazione: gli hook girano al di fuori di essa, e il loro output per Stop e Notification non viene mostrato al modello. Però il blocco `env` vale per l'intera sessione, quindi un comando Bash eseguito da Claude potrebbe leggere la variabile. Se questo è un problema, tieni la chiave in un file leggibile solo da te, per esempio `~/.config/pocketalert/key` con permessi `600`, e nello script usa `-H "Token: $(cat ~/.config/pocketalert/key)"`.

### Qual è la differenza rispetto al suono del terminale?

Il suono del terminale e le notifiche desktop richiedono che tu sia davanti al computer. Una push raggiunge il telefono ovunque tu sia, conserva una cronologia e può essere impostata per superare Full immersion per i prompt che bloccano Claude.

### Posso ricevere la risposta intera, non 300 caratteri?

Una push può contenere fino a circa 3.000 caratteri di testo. Puoi alzare il limite `0:300`, ma una push serve a decidere se tornare alla scrivania, non a leggere la risposta completa.

### È gratuito?

Sì. Gli hook fanno parte di Claude Code, e il piano gratuito di Pocket Alert copre 50 messaggi al giorno su un dispositivo. I piani a pagamento aggiungono più messaggi, dispositivi e pulsanti di azione.

[Ottieni una chiave API](/signup), inserisci lo script e lascia che Claude ti avvisi quando tocca a te.
