Indice
- Quale hook per quale situazione
- Cosa ti serve
- Passo 1 — Crea due canali
- Passo 2 — Aggiungi gli hook
- Passo 3 — Provalo senza aspettare una richiesta vera
- Passo 4 — Fai squillare il canale dei blocchi
- Evitare il sovraccarico di notifiche
- Claude Code da remoto o in CI
- Risoluzione dei problemi
- Domande frequenti
- Come ricevo una notifica quando Claude Code ha bisogno di un permesso?
- Come faccio a sapere quando Claude Code finisce un task?
- La notifica può superare Non disturbare?
- Funziona con Claude Code sul web o nelle sessioni remote?
- È sicuro mettere l'URL del webhook in settings.json?
- In sintesi
- Correlati
Claude Code si ferma in due situazioni che contano: è bloccato in attesa di te (una richiesta di permesso, una domanda) oppure ha finito. Se non stai guardando il terminale, le due cose sembrano identiche: non succede niente e la sessione resta ferma finché non torni. La soluzione è un hook: poche righe in settings.json che mandano un webhook al tuo telefono appena si verifica una delle due.
Questa guida ti dà la configurazione da copiare, spiega quale evento hook usare in ogni situazione e copre i dettagli che lo fanno funzionare in modo affidabile: leggere l'input dell'hook, le virgolette nella shell e come non affogare nelle notifiche.
Quale hook per quale situazione
Claude Code esegue gli hook sugli eventi del suo ciclo di vita. Due di questi coprono il problema (documentazione degli hook):
| Vuoi sapere quando… | Evento hook | Matcher / filtro |
|---|---|---|
| Claude attende una decisione su un permesso | Notification | permission_prompt |
| Claude è inattivo e attende il tuo input | Notification | idle_prompt |
| Claude ha finito di rispondere | Stop | non serve |
Il matcher dell'hook Notification filtra in base al tipo di notifica, quindi puoi scegliere esattamente quali arrivano sul telefono. L'input arriva come JSON su stdin e include notification_type, message, cwd e session_id. Gli hook Notification non possono bloccare né modificare nulla: sono osservatori, ed è proprio ciò che serve qui.
L'input di Stop include last_assistant_message, l'ultimo testo prodotto da Claude. È una riga di riepilogo gratuita per la notifica.
Cosa ti serve
- Echobell sul telefono (App Store / Google Play)
curlejqsulla macchina che esegue Claude Code- Due minuti
Passo 1 — Crea due canali
Resisti alla tentazione di mandare tutto su un solo canale. In Echobell crea:
- Claude Bloccato, tipo Time Sensitive o Chiamata — per le richieste di permesso, dove l'agente è fermo e ogni minuto è calcolo e tempo reale sprecati
- Claude Finito, tipo Normale — una normale notifica push, da leggere quando vuoi
Copia l'URL del webhook di ciascun canale. Assomiglia a https://hook.echobell.one/t/<channel-token>. Trattalo come una password: chiunque lo abbia può far squillare il tuo telefono.
Salva entrambi come variabili d'ambiente, così non finiscono mai in un file di configurazione sotto versionamento:
export ECHOBELL_CLAUDE_BLOCKED_URL="https://hook.echobell.one/t/<blocked-token>"
export ECHOBELL_CLAUDE_DONE_URL="https://hook.echobell.one/t/<done-token>"Mettile nel profilo della shell, così Claude Code le eredita.
Passo 2 — Aggiungi gli hook
Aggiungi questo a ~/.claude/settings.json per applicarlo a ogni progetto, oppure a .claude/settings.local.json per un solo repository:
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt",
"hooks": [
{
"type": "command",
"command": "jq -c '{title: \"Claude ha bisogno di un permesso\", body: .message, project: (.cwd | split(\"/\") | last)}' | curl -sS -m 10 -X POST -H 'Content-Type: application/json' -d @- \"$ECHOBELL_CLAUDE_BLOCKED_URL\""
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "jq -c '{title: \"Claude ha finito\", body: (.last_assistant_message // \"Fatto\" | .[0:200]), project: (.cwd | split(\"/\") | last)}' | curl -sS -m 10 -X POST -H 'Content-Type: application/json' -d @- \"$ECHOBELL_CLAUDE_DONE_URL\""
}
]
}
]
}
}Cosa fa ogni pezzo:
jq -c '{...}'legge il JSON dell'hook da stdin e costruisce un piccolo payload, così Echobell riceve esattamente i campi che vuoi e non l'intero documento dell'hook..cwd | split("/") | lasttrasforma/home/me/code/apiinapi, così la notifica dice quale progetto sta chiedendo..[0:200]tronca il messaggio finale. Il worker di Echobell limita il corpo delle notifiche a 1500 byte, e comunque la schermata di blocco ne mostra molto meno.-m 10dà acurlun timeout di 10 secondi, così un problema di rete non lascia mai Claude Code in attesa del tuo hook.
Echobell mostra le chiavi che invii attraverso i template del canale, e un canale nuovo non ha alcun template che le legga: impostali nelle impostazioni del canale, template del titolo {{title}} e template del corpo {{body}}. Aggiungi {{project}} a uno dei due se vuoi vedere il nome del progetto, per esempio {{title}} ({{project}}).
Passo 3 — Provalo senza aspettare una richiesta vera
Esegui a mano la stessa pipeline con un payload d'hook finto:
echo '{"message":"Claude ha bisogno del tuo permesso per usare Bash","cwd":"/home/me/code/api","notification_type":"permission_prompt"}' \
| jq -c '{title: "Claude ha bisogno di un permesso", body: .message, project: (.cwd | split("/") | last)}' \
| curl -sS -m 10 -X POST -H 'Content-Type: application/json' -d @- "$ECHOBELL_CLAUDE_BLOCKED_URL"Se il telefono si illumina, il lato Echobell funziona e ogni problema residuo sta nel modo in cui Claude Code legge la configurazione. In Claude Code esegui /hooks per confermare che gli hook siano stati caricati; le modifiche alle impostazioni fatte con una sessione in corso potrebbero richiedere il menu degli hook o un riavvio per avere effetto.
Passo 4 — Fai squillare il canale dei blocchi
Una notifica push perde contro Non disturbare. Un canale Chiamata si comporta come una chiamata in arrivo e attraversa la modalità Full Immersion di iOS, cosa che conta soprattutto quando avvii un task lungo e te ne vai per la serata. Se vuoi essere interrotto solo per alcune richieste, filtra con una condizione del canale Echobell sulle variabili che invii, per esempio project == "api", invece di modificare l'hook. Per l'elenco completo delle variabili vedi la documentazione delle condizioni.
Evitare il sovraccarico di notifiche
Una sessione intensa può generare molti eventi Stop: ogni risposta ne termina con uno. Tre modi per tenere il segnale:
- Non mandare
Stopa un canale che squilla. Aver finito non è urgente; tienilo su Normale. - Usa
idle_promptal posto diStopse vuoi sapere solo quando Claude si è fermato e ti aspetta, invece che dopo ogni risposta. - Restringi per progetto con una condizione, così un repository di prova non ti notifica affatto.
Claude Code da remoto o in CI
Lo stesso approccio funziona in ambienti cloud o remoti, perché l'hook è solo una richiesta HTTPS in uscita. Nulla deve essere raggiungibile da internet. Imposta le due variabili d'ambiente nei secret dell'ambiente invece che nel profilo della shell, e la notifica arriva sul telefono ovunque giri la sessione.
Risoluzione dei problemi
Non arriva nulla e fallisce anche il test manuale. Controlla che la variabile con l'URL sia impostata nella shell che avvia Claude Code: echo "$ECHOBELL_CLAUDE_BLOCKED_URL". Una variabile vuota fa fallire curl in silenzio.
Il test manuale funziona ma l'hook non scatta. Verifica il matcher: permission_prompt e idle_prompt sono distinti, e un matcher che non corrisponde semplicemente non viene mai eseguito. Esegui /hooks e controlla che il JSON sia valido: una virgola finale disattiva gli hook dell'intero file di impostazioni.
Il corpo della notifica è vuoto. Il filtro jq ha fatto riferimento a un campo che non esiste per quell'evento. message esiste nell'input di Notification; last_assistant_message esiste in quello di Stop. Usa // per fornire un valore predefinito, come nella configurazione sopra.
Scatta troppo spesso. Vedi la sezione precedente: passa da Stop a idle_prompt, oppure aggiungi una condizione.
Domande frequenti
Come ricevo una notifica quando Claude Code ha bisogno di un permesso?
Aggiungi un hook Notification con il matcher permission_prompt che invii un webhook a un canale. Echobell trasforma quella richiesta in un push o in un avviso in stile chiamata sul tuo telefono.
Come faccio a sapere quando Claude Code finisce un task?
Aggiungi un hook Stop. Viene eseguito quando Claude finisce di rispondere e il suo input include last_assistant_message, che puoi usare come corpo della notifica.
La notifica può superare Non disturbare?
Sì, se il canale ricevente è di tipo Chiamata. Si comporta come una chiamata in arrivo, che la modalità Full Immersion di iOS lascia passare. Un normale push di qualsiasi app no.
Funziona con Claude Code sul web o nelle sessioni remote?
Sì. L'hook fa solo una richiesta HTTPS in uscita, quindi funziona ovunque la sessione possa raggiungere internet. Fornisci gli URL dei canali tramite i secret dell'ambiente.
È sicuro mettere l'URL del webhook in settings.json?
Meglio una variabile d'ambiente, come mostrato sopra, così il token non finisce in un repository. Se trapela, crea un nuovo canale e ritira il vecchio.
In sintesi
Due canali, due hook e una pipeline jq | curl: un canale Chiamata o Time Sensitive per permission_prompt, un canale Normale per Stop. Dopodiché puoi avviare un task lungo di un agente, uscire dalla stanza ed essere richiamato solo quando l'agente ha davvero bisogno di te.
Scarica Echobell per iPhone oppure scaricalo da Google Play, poi esegui il test manuale qui sopra prima di affidargli un task lungo.