Notifiche push di Claude Code con ntfy (fai-da-te)

01Passo 1: scegli un topic e iscriviti

ntfy non richiede registrazione. Un topic viene creato la prima volta che qualcuno ci pubblica o si iscrive, e chiunque ne conosca il nome può leggerlo. La documentazione di ntfy dice che il topic è in pratica una password, quindi rendilo lungo e casuale, per esempio claude-7f3k9q2xw4mz. I nomi dei topic possono contenere lettere, numeri, underscore e trattini, fino a 64 caratteri.

Installa l'app ntfy (App Store, Google Play o F-Droid), tocca + e iscriviti al tuo topic su ntfy.sh.

Verifica che funzioni da un terminal:

curl -H "Title: Test" -d "Hello from my computer" https://ntfy.sh/claude-7f3k9q2xw4mz

Il telefono dovrebbe vibrare entro un paio di secondi. Su Windows, curl.exe è incluso in Windows 10 e 11 e accetta la stessa riga.

02Passo 2: uno script per l'hook (Mac e Linux)

Claude Code passa a ogni hook un oggetto JSON sullo standard input. Entrambi gli eventi hanno campi in comune come cwd e hook_event_name. Notification aggiunge message e notification_type, mentre Stop aggiunge last_assistant_message, il testo della risposta finale di Claude. Questo script trasforma entrambi in una push leggibile. Richiede jq (brew install jq, oppure apt install jq su Debian e Ubuntu).

Salvalo come ~/.claude/ntfy-notify.sh ed esegui chmod +x ~/.claude/ntfy-notify.sh:

#!/bin/sh
TOPIC_URL="https://ntfy.sh/claude-7f3k9q2xw4mz"

input=$(cat)
event=$(printf '%s' "$input" | jq -r '.hook_event_name')
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")

if [ "$event" = "Stop" ]; then
  title="Claude finished: $project"
  body=$(printf '%s' "$input" | jq -r '(.last_assistant_message // "Done") | .[0:300]')
  priority=3
else
  title="Claude needs you: $project"
  body=$(printf '%s' "$input" | jq -r '.message // "Needs your attention"')
  priority=4
fi

curl -s -H "Title: $title" -H "Priority: $priority" -H "Tags: robot" \
  -d "$body" "$TOPIC_URL" > /dev/null
exit 0

La priorità va da 1 (minima) a 5 (urgente). Tags aggiunge un'emoji alla notifica; robot mostra la faccina di un robot.

03Passo 3: collegalo a settings.json

Aggiungi gli hook a ~/.claude/settings.json. Se il file ha già un oggetto hooks, aggiungi questi eventi al suo interno invece di sostituirlo.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "~/.claude/ntfy-notify.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/ntfy-notify.sh", "async": true }
        ]
      }
    ]
  }
}

"async": true fa sì che l'hook Stop invii in background, così una rete lenta non rallenta mai Claude. Avvia una nuova sessione di Claude Code, perché gli hook vengono caricati all'avvio della sessione.

Stop o idle_prompt?

Stop scatta appena Claude finisce, anche se sei davanti alla tastiera. Se è troppo, elimina il blocco Stop e usa invece il matcher permission_prompt|idle_prompt. Secondo la documentazione di Anthropic, idle_prompt scatta circa 60 secondi dopo che Claude ha finito, solo se nel frattempo non hai digitato nulla, e permission_prompt scatta quando una richiesta di permesso è rimasta in attesa per circa sei secondi senza che tu abbia premuto un tasto. Così ottieni gratis un filtro approssimativo "solo quando non ci sono". La guida al Notification hook e la guida allo Stop hook coprono tutti i campi e le tempistiche.

04Windows (PowerShell)

Su Windows, salva questo come %USERPROFILE%\.claude\ntfy-notify.ps1. Non serve installare altro:

$in = [Console]::In.ReadToEnd() | ConvertFrom-Json
$project = Split-Path $in.cwd -Leaf

if ($in.hook_event_name -eq 'Stop') {
  $title = "Claude finished: $project"
  $body = [string]$in.last_assistant_message
  if ($body.Length -gt 300) { $body = $body.Substring(0, 300) }
  $priority = '3'
} else {
  $title = "Claude needs you: $project"
  $body = [string]$in.message
  $priority = '4'
}

Invoke-RestMethod -Method Post -Uri 'https://ntfy.sh/claude-7f3k9q2xw4mz' `
  -Headers @{ Title = $title; Priority = $priority } `
  -Body ([Text.Encoding]::UTF8.GetBytes($body)) | Out-Null

Poi usa questa voce dell'hook al posto delle righe command viste sopra:

{
  "type": "command",
  "shell": "powershell",
  "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"$HOME\\.claude\\ntfy-notify.ps1\""
}

Se esegui Claude Code dentro WSL, usa lo script per Mac e Linux: per l'hook, WSL è Linux a tutti gli effetti.

05Mantenere la privacy

Tutto il contenuto della push passa dal server ntfy, e su ntfy.sh chiunque conosca il nome del topic può leggerlo. Il messaggio Stop qui sopra include l'inizio della risposta di Claude, che può contenere codice o nomi di file. Tre modi per renderlo più sicuro:

1. Invia meno dati. Sostituisci il corpo di Stop con una stringa fissa come "Done" e lascia solo il nome del progetto nel titolo.
2. Usa un access token. ntfy accetta -H "Authorization: Bearer tk_..." su qualsiasi pubblicazione. Sul tuo server, imposta auth-default-access: "deny-all", crea un utente con ntfy user add e un token con ntfy token add.
3. Usa un server tuo. ntfy è self-hostable. Per la consegna istantanea all'app per iPhone, la documentazione di ntfy dice di impostare upstream-base-url: "https://ntfy.sh", che inoltra a ntfy.sh solo l'ID del messaggio e un hash del topic per svegliare il telefono; l'app poi scarica il messaggio dal tuo server.

Se Claude Code gira su un server remoto, lo stesso hook funziona lì senza modifiche, il che rende ntfy ideale per le notifiche via SSH.

06Dove si inserisce Claude Code Notifier

Per gli avvisi unidirezionali, la configurazione qui sopra è una soluzione completa e non cercheremmo di dissuaderti. Però si limita ad avvisarti. Quando la push dice che Claude ha bisogno di un permesso, la sessione resta comunque in attesa finché non torni alla tastiera.

ntfy supporta pulsanti di azione che eseguono una richiesta HTTP, quindi potresti costruirti da solo un modo per rispondere: un hook PermissionRequest che pubblica la richiesta, attende una risposta su un secondo topic e restituisce una decisione. Alcuni progetti open source fanno proprio questo (vedi il confronto).

Claude Code Notifier offre tutto questo già pronto. Con un telefono associato puoi consentire una volta, consentire per la sessione o negare un permesso, scegliere una risposta quando Claude fa una domanda e inviare l'istruzione successiva quando Claude ha finito, tutto dal telefono. Controlla anche se sei presente: se hai digitato negli ultimi 30 secondi, il terminal chiede come al solito e il telefono non resta in attesa di nulla. Se non ci sei, il terminal attende la tua risposta fino a un limite che imposti tu, e smette di aspettare appena tocchi la tastiera. ccn funziona su Mac, Windows e Linux; vedi la pagina di ccn e i prezzi delle app per telefono.

07FAQ