Notifiche di Claude Code su macOS

01Cosa fa Claude Code da solo

Claude Code genera un evento di notifica quando finisce un task o aspetta un permesso e sembra che tu non sia al terminal. Cosa vedi dipende dal terminal, secondo la guida al terminal di Anthropic:

Per iTerm2, apri Settings > Profiles > Terminal, spunta Notification Center Alerts, poi fai clic su Filter Alerts e attiva Send escape sequence-generated alerts. Controlla anche che iTerm2 possa inviare notifiche in Impostazioni di Sistema > Notifiche.

In Apple Terminal puoi almeno avere un suono. Imposta "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json e attiva Campanello udibile in Impostazioni > Profili > Avanzate. La guida al campanello del terminal spiega questa strada nel dettaglio.

L'avviso integrato ha dei limiti: scatta solo quando Claude Code pensa che tu sia via, dice solo che è successo qualcosa e non esce mai dal computer.

02Un hook di notifica con osascript

Un hook funziona in ogni terminal, compresi quelli degli IDE. Questo è l'esempio per macOS della guida agli hook di Anthropic. Aggiungilo a ~/.claude/settings.json, mantenendo le altre chiavi che hai già:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Digita /hooks in Claude Code per verificare che compaia sotto Notification.

Il permesso di Script Editor

osascript pubblica le notifiche come Script Editor. Se Script Editor non ha il permesso per le notifiche, il comando fallisce in silenzio e macOS non te lo chiede. Esegui questo una volta nel Terminale:

osascript -e 'display notification "test"'

La prima volta non compare nulla. Apri Impostazioni di Sistema > Notifiche, trova Script Editor e attiva Consenti notifiche. Riesegui il comando e la notifica di prova dovrebbe apparire.

Quando scatta

Il matcher vuoto scatta su ogni tipo di notifica. I due più utili sono permission_prompt (Claude aspetta un'approvazione da circa sei secondi e non hai digitato nulla) e idle_prompt (Claude ha finito circa 60 secondi fa e da allora non hai digitato nulla). La guida al Notification hook elenca tutti i tipi e le relative tempistiche.

03Sapere subito quando Claude finisce

idle_prompt aspetta un minuto. Per essere avvisato subito, aggiungi un hook Stop, che viene eseguito quando Claude termina il suo turno. Stop non accetta matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

sound name accetta qualsiasi suono in /System/Library/Sounds, come Glass, Ping o Hero. Se vuoi solo un suono, come comando va bene afplay /System/Library/Sounds/Glass.aiff. Trovi altro su questo evento nella guida allo Stop hook.

04Mostrare il messaggio reale

Gli hook ricevono JSON sullo standard input. L'input di Notification ha un campo message, ad esempio "Claude needs your permission". Un piccolo script può mettere quel testo nella notifica. Salvalo come ~/.claude/hooks/notify-mac.sh:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
osascript -e 'on run argv' \
  -e 'display notification (item 1 of argv) with title "Claude Code"' \
  -e 'end run' "$msg"

Passando il testo come argomento, e non dentro la stringa AppleScript, eventuali virgolette nel messaggio non possono rompere il comando. Rendilo eseguibile con chmod +x ~/.claude/hooks/notify-mac.sh e imposta come comando dell'hook ~/.claude/hooks/notify-mac.sh. Lo script richiede jq (brew install jq se jq --version fallisce).

05terminal-notifier: clicca per tornare al terminal

Una notifica di osascript, se cliccata, apre Script Editor, che non è dove vuoi andare. terminal-notifier ti permette di scegliere quale app portare in primo piano:

brew install terminal-notifier
terminal-notifier -title "Claude Code" -message "Claude has finished" -sound default -activate com.googlecode.iterm2

Usa com.apple.Terminal per Apple Terminal, oppure il bundle ID del tuo editor. Lo stesso comando va nel campo command dell'hook. La prima volta consenti le notifiche per terminal-notifier in Impostazioni di Sistema.

06Full immersion e Non disturbare

Sono tutte normali notifiche di macOS, quindi una modalità Full immersion può nasconderle. Se spariscono in certi orari, controlla Impostazioni di Sistema > Full immersion e consenti l'app che le pubblica (Script Editor, terminal-notifier o il tuo terminal). Per notifiche che rispettino invece i tuoi orari, vedi ore di silenzio e Non disturbare.

07Dove si inserisce Claude Code Notifier

Gli hook qui sopra sono un'ottima soluzione se stai al Mac e vuoi solo un promemoria. Non bastano più quando ti allontani, perché una notifica del Mac non ti raggiunge in cucina e non può rispondere a Claude.

Claude Code Notifier è uno strumento indipendente (creato da TouchTap, non da Anthropic) basato sugli stessi hook. Il suo tool da riga di comando gratuito, ccn, funziona su Mac, Windows e Linux. Installalo sul Mac con:

curl -fsSL https://claudecodenotifier.com/install.sh | sh

oppure con Homebrew: brew trust --formula touch-tap/tap/ccn && brew install touch-tap/tap/ccn. Aggiunge le sue voci di hook a ~/.claude/settings.json, lascia intatto il resto del file e ne conserva un backup. Da quel momento mostra una notifica di macOS quando Claude finisce, ha bisogno di un permesso o fa una domanda, senza bisogno di rete né di telefono.

Se abbini un iPhone o un telefono Android, gli stessi eventi arrivano come notifiche push, e dal telefono puoi consentire o negare un permesso, scegliere una risposta alla domanda di Claude o inviare l'istruzione successiva. Se hai digitato negli ultimi 30 secondi, il terminal chiede come al solito e sul telefono non resta nulla in attesa. Vedi abbinare un telefono e la pagina di ccn. Le app per telefono richiedono un abbonamento o un acquisto a vita; vedi i prezzi.

Se aggiungi ccn, rimuovi i tuoi hook con osascript, altrimenti vedrai due notifiche per ogni evento. Esiste anche una vecchia app per la barra dei menu del Mac: non usarla insieme a ccn sullo stesso Mac.

08FAQ