Notifiche di Claude Code su Linux

01Cosa fa Claude Code da solo

Quando Claude finisce un task o aspetta un permesso e sembri assente, Claude Code genera un evento di notifica. La guida al terminale di Anthropic dice che Ghostty e Kitty lo trasformano in una notifica desktop; altri terminali, come GNOME Terminal, Konsole o il terminale di VS Code, non mostrano nulla.

In alternativa puoi chiedere un bell in qualsiasi terminale:

{
  "preferredNotifChannel": "terminal_bell"
}

Cosa fa il bell dipende dal terminale e dal desktop: può emettere un beep, far lampeggiare la finestra o segnarla come urgente. Ne parla la guida al terminal bell. Per una vera notifica, usa un hook.

02Installa notify-send

Controlla se ce l'hai:

notify-send 'Claude Code' 'test'

Se il comando non viene trovato, installalo:

sudo apt install libnotify-bin   # Debian, Ubuntu, Mint
sudo dnf install libnotify       # Fedora, RHEL
sudo pacman -S libnotify         # Arch

Se il comando parte ma non compare nulla, non hai un demone di notifica. GNOME, KDE Plasma, Cinnamon e Xfce ne includono uno. Su un tiling window manager come Sway, i3 o Hyprland, installane e avviane uno tu, per esempio mako o dunst. Funzionano sia Wayland sia X11, perché notify-send parla con il demone via D-Bus, non con il display.

03Un Notification hook

Questo è l'esempio per Linux della guida agli hook di Anthropic. Aggiungilo a ~/.claude/settings.json, accanto alle chiavi che hai già:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Digita /hooks in Claude Code per vederlo elencato sotto Notification. Il matcher vuoto scatta per ogni tipo di notifica. I principali sono permission_prompt, dopo che un'approvazione aspetta circa sei secondi senza che tu scriva, e idle_prompt, circa 60 secondi dopo che Claude ha finito. La guida al Notification hook ha l'elenco completo.

04Sapere subito quando Claude finisce

idle_prompt arriva con un minuto di ritardo. Un hook Stop parte appena Claude chiude il suo turno. Non vuole matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -a 'Claude Code' 'Claude Code' 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

-a imposta il nome dell'app mostrato dal demone. Altre opzioni utili: -u critical lascia la notifica a schermo finché non la chiudi (sulla maggior parte dei demoni) e -i dialog-information aggiunge un'icona. Trovi altro su questo evento nella guida allo Stop hook.

05Mostra il messaggio vero, con un suono

Gli hook ricevono JSON sullo standard input, e l'input di Notification include un campo message. Uno script può mostrare quel testo e riprodurre un suono. Salva questo come ~/.claude/hooks/notify-linux.sh:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
notify-send -a 'Claude Code' 'Claude Code' "$msg"
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true

Rendilo eseguibile con chmod +x ~/.claude/hooks/notify-linux.sh e usa ~/.claude/hooks/notify-linux.sh come comando dell'hook. jq è nei pacchetti di ogni distribuzione. paplay funziona con PulseAudio e con il layer PulseAudio di PipeWire, e il file audio viene dal tema sonoro freedesktop (sound-theme-freedesktop su Debian e Ubuntu). Puoi usare qualsiasi .oga o .wav.

06Niente notify-send? Usa una escape sequence

Se il tuo terminale capisce le escape sequence di notifica, un hook può chiedere a Claude Code di inviarne una. Gli hook non hanno un terminale proprio, quindi restituisci la sequenza in un campo terminalSequence e Claude Code la scrive. La reference di Anthropic indica OSC 777 per Ghostty, urxvt e Warp, e OSC 99 per Kitty. Per esempio:

#!/bin/bash
body=$(jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Non serve nessun demone sulla macchina dove gira Claude Code, ed è per questo che è anche il trucco per i server remoti via SSH.

07Quando notify-send funziona in una shell ma non da Claude Code

notify-send ha bisogno dell'indirizzo della sessione D-Bus del tuo login desktop. Gli hook ereditano l'ambiente di Claude Code, quindi se avvii Claude Code da un terminal del desktop va tutto bene. Se invece lo avvii via SSH, da un servizio systemd, in un container o dentro un server tmux avviato la prima volta da SSH, Claude Code potrebbe non averlo, e la notifica si perde nel nulla. Esegui echo $DBUS_SESSION_BUS_ADDRESS nella stessa shell da cui avvii claude: se è vuoto, le notifiche desktop di quella sessione non verranno mostrate. La guida a tmux e la guida a SSH spiegano come gestire questi casi.

08Dove si inserisce Claude Code Notifier

Gli hook qui sopra vanno benissimo quando sei al computer. Ma non ti raggiungono quando ti allontani dalla scrivania, e una notifica desktop non può rispondere a Claude.

Claude Code Notifier è uno strumento indipendente (fatto da TouchTap, non da Anthropic) basato sugli hook di Claude Code. Il suo tool da riga di comando gratuito, ccn, gira su Mac, Windows e Linux. Su Linux:

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

oppure npx @touchtap/ccn se hai Node.js. Aggiunge le sue voci di hook a ~/.claude/settings.json, lascia intatto tutto il resto e tiene un backup. Da lì in poi mostra una notifica desktop Linux quando Claude finisce, chiede un permesso o fa una domanda. Questa parte non richiede rete né telefono. Gira per pochi millisecondi a evento; nulla resta attivo in background.

Associa un telefono iPhone o Android e gli stessi eventi arrivano come notifiche push, anche su una macchina senza desktop. Dal telefono puoi consentire o negare un permesso, scegliere una risposta alla domanda di Claude e inviare la prossima istruzione quando Claude ha finito. Vedi associare un telefono, la pagina di ccn e i prezzi delle app per telefono. Su Linux, ccn conserva il token in un file leggibile solo da te.

Se installi ccn, rimuovi i tuoi hook notify-send per evitare doppioni.

09FAQ