# Notifiche cmux supporta le notifiche desktop, permettendo agli agenti IA e agli script di avvisarti quando hanno bisogno di attenzione. ## Ciclo di vita 1. Ricevuta: la notifica appare nel pannello, l'avviso desktop si attiva (se non soppresso) 2. Non letta: badge mostrato sul tab del workspace 3. Letta: cancellata quando visualizzi quel workspace 4. Cancellata: rimossa dal pannello ### Soppressione Gli avvisi desktop vengono soppressi quando: - La finestra cmux è attiva - Il workspace specifico che invia la notifica è attivo - Il pannello notifiche è aperto ### Pannello notifiche Premi `⌘⇧I` per aprire il pannello notifiche. Clicca su una notifica per andare a quel workspace. Premi `⌘⇧U` per andare direttamente al workspace con la notifica non letta più recente. ## Comando personalizzato Esegui un comando shell ogni volta che una notifica è pianificata. Impostalo in Impostazioni > App > Comando di notifica. Il comando viene eseguito tramite /bin/sh -c con queste variabili d'ambiente: | Variabile | Descrizione | | --- | --- | | `CMUX_NOTIFICATION_TITLE` | Titolo della notifica (nome del workspace o dell'app) | | `CMUX_NOTIFICATION_SUBTITLE` | Sottotitolo della notifica | | `CMUX_NOTIFICATION_BODY` | Testo del corpo della notifica | Examples ``` # Text-to-speech say "$CMUX_NOTIFICATION_TITLE" # Custom sound file afplay /path/to/sound.aiff # Log to file echo "$CMUX_NOTIFICATION_TITLE: $CMUX_NOTIFICATION_BODY" >> ~/notifications.log ``` Il comando viene eseguito indipendentemente dal selettore di suoni di sistema. Imposta il selettore su "Nessuno" per usare solo il comando personalizzato, o mantieni entrambi per un suono di sistema più un'azione personalizzata. ## Hook di notifica `cmux.json` può definire hook di notifica che ricevono ogni criterio di notifica come JSON su stdin. Ogni hook restituisce JSON su stdout. Gli hook sono disattivati per impostazione predefinita; cmux li esegue solo quando `notifications.hooks` contiene almeno un hook abilitato. cmux applica il testo e gli effetti restituiti, così gli hook possono filtrare banner, mantenere o saltare la cronologia della barra laterale, eseguire suoni o fermare gli hook successivi. cmux.json ``` { "notifications": { "hooks": [ { "id": "quiet-docs", "command": "sed 's/"desktop":true/"desktop":false/'", "timeoutSeconds": 20 } ] } } ``` Input e output dell’hook ``` { "version": 1, "notification": { "workspaceId": "3B3F0D83-...", "surfaceId": "7E9C1A02-...", "title": "Codex", "subtitle": "Waiting", "body": "Agent needs input" }, "context": { "cwd": "/path/to/project", "configPath": "/path/to/project/.cmux/cmux.json", "hookId": "quiet-docs", "appFocused": false, "focusedPanel": false }, "agent": { "kind": "claude", "category": "turn-complete", "pending": false, "isSubagent": true }, "effects": { "record": true, "markUnread": true, "reorderWorkspace": true, "desktop": true, "sound": true, "command": true, "paneFlash": true } } ``` Gli hook vengono ereditati dal file globale `~/.config/cmux/cmux.json` e dai file di progetto `.cmux/cmux.json`, dalle directory padre fino al workspace corrente. Gli hook di progetto usano lo stesso prompt di fiducia degli altri comandi di progetto `cmux.json` prima dell’esecuzione. Anche i banner di approvazione del Feed passano da questi hook; disattivare `desktop` sopprime il banner nativo mantenendo l’elemento Feed disponibile in cmux. Imposta `notifications.hooksMode` su `replace` in una configurazione di progetto per ignorare gli hook ereditati. Se un hook fallisce, scade o restituisce JSON non valido, cmux usa il comportamento di notifica predefinito e mostra un avviso di errore dell’hook. ### Agent-event context Notifications that originate from an agent completion signal carry a read-only `agent` object: `kind` is the stable lowercase agent slug (claude, codex, grok, …), `category` is turn-complete, needs-permission, or idle-reminder, `pending` is true when the turn ended with background work still running, and `isSubagent` is true for nested subagent sessions. The object is omitted for non-agent notifications, and the same values are exported to the hook process as CMUX\_NOTIFICATION\_AGENT\_KIND, CMUX\_NOTIFICATION\_AGENT\_CATEGORY, CMUX\_NOTIFICATION\_AGENT\_PENDING, and CMUX\_NOTIFICATION\_AGENT\_IS\_SUBAGENT. For example, this hook silences the banner, sound, and pane flash for subagent completions while leaving everything else untouched: Silence subagent completions ``` { "notifications": { "hooks": [ { "id": "mute-subagent-completions", "command": "if [ \"${CMUX_NOTIFICATION_AGENT_IS_SUBAGENT-0}\" = \"1\" ] && [ \"$CMUX_NOTIFICATION_AGENT_CATEGORY\" = \"turn-complete\" ]; then printf '{\"effects\":{\"desktop\":false,\"sound\":false,\"paneFlash\":false}}'; fi" } ] } } ``` With no hooks configured, notification behavior is exactly cmux's built-in default — configuring a hook is the explicit opt-in that hands the delivery decision to your script. Note that cmux's built-in subagent suppression (`automation.suppressSubagentNotifications`, on by default) drops subagent completion events before they reach hooks; turn it off if your hook should see subagent events and make its own decision. ## Invio di notifiche ### CLI ``` cmux notify --title "Task Complete" --body "Your build finished" cmux notify --title "Claude Code" --subtitle "Waiting" --body "Agent needs input" ``` ### OSC 777 (semplice) Il protocollo RXVT usa un formato fisso con titolo e corpo: ``` printf '\e]777;notify;My Title;Message body here\a' ``` Shell function ``` notify_osc777() { local title="$1" local body="$2" printf '\e]777;notify;%s;%s\a' "$title" "$body" } notify_osc777 "Build Complete" "All tests passed" ``` ### OSC 99 (ricco) Il protocollo Kitty supporta sottotitoli e ID di notifica: ``` # Format: ESC ] 99 ; ; ESC \ # Simple notification printf '\e]99;i=1;e=1;d=0:Hello World\e\\' # With title, subtitle, and body printf '\e]99;i=1;e=1;d=0;p=title:Build Complete\e\\' printf '\e]99;i=1;e=1;d=0;p=subtitle:Project X\e\\' printf '\e]99;i=1;e=1;d=1;p=body:All tests passed\e\\' ``` | Funzionalità | OSC 99 | OSC 777 | | --- | --- | --- | | Titolo + corpo | Sì | Sì | | Sottotitolo | Sì | No | | ID notifica | Sì | No | | Complessità | Maggiore | Minore | Usa OSC 777 per notifiche semplici. Usa OSC 99 quando hai bisogno di sottotitoli o ID di notifica. Usa il CLI (cmux notify) per l'integrazione più semplice. ## Hook di Claude Code cmux si integra con [Claude Code](https://docs.anthropic.com/en/docs/claude-code) tramite hook per notificarti quando le attività sono completate. ### 1\. Crea lo script hook ~/.claude/hooks/cmux-notify.sh ``` #!/bin/bash # Outside cmux there is no socket to talk to, so do nothing. [ -S /tmp/cmux.sock ] || exit 0 payload=$(cat) field() { printf '%s' "$payload" | jq -r "$1 // empty"; } event=$(field .hook_event_name) if [ "$event" = "Stop" ]; then cmux notify --title "Claude Code" --body "Session complete" elif [ "$event" = "SubagentStop" ]; then cmux notify --title "Claude Code" --body "Agent finished" fi ``` ``` chmod +x ~/.claude/hooks/cmux-notify.sh ``` ### 2\. Configura Claude Code ~/.claude/settings.json ``` { "hooks": { "SubagentStop": [ { "hooks": [{ "type": "command", "command": "~/.claude/hooks/cmux-notify.sh" }] } ], "Stop": [ { "hooks": [{ "type": "command", "command": "~/.claude/hooks/cmux-notify.sh" }] } ] } } ``` Riavvia Claude Code per applicare gli hook. ## GitHub Copilot CLI Copilot CLI supporta gli [hook](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks) che eseguono comandi shell in eventi del ciclo di vita come l'invio di prompt, l'arresto dell'agente e gli errori. ~/.copilot/config.json ``` { "hooks": { "userPromptSubmitted": [ { "type": "command", "bash": "if command -v cmux &>/dev/null; then cmux set-status copilot_cli Running; fi", "timeoutSec": 3 } ], "agentStop": [ { "type": "command", "bash": "if command -v cmux &>/dev/null; then cmux notify --title 'Copilot CLI' --body 'Done'; cmux set-status copilot_cli Idle; fi", "timeoutSec": 5 } ], "errorOccurred": [ { "type": "command", "bash": "if command -v cmux &>/dev/null; then cmux notify --title 'Copilot CLI' --subtitle 'Error' --body 'An error occurred'; cmux set-status copilot_cli Error; fi", "timeoutSec": 5 } ], "sessionEnd": [ { "type": "command", "bash": "if command -v cmux &>/dev/null; then cmux clear-status copilot_cli; fi", "timeoutSec": 3 } ] } } ``` Per gli hook a livello di repository, crea un file .github/hooks/notify.json con la stessa struttura: .github/hooks/notify.json ``` { "version": 1, "hooks": { "userPromptSubmitted": [ ... ], "agentStop": [ ... ] } } ``` ## Esempi di integrazione ### Notifica dopo un comando lungo ~/.zshrc ``` # Add to your shell config notify-after() { "$@" local exit_code=$? if [ $exit_code -eq 0 ]; then cmux notify --title "✓ Command Complete" --body "$1" else cmux notify --title "✗ Command Failed" --body "$1 (exit $exit_code)" fi return $exit_code } # Usage: notify-after npm run build ``` ### Python python ``` import sys def notify(title: str, body: str): """Send OSC 777 notification.""" sys.stdout.write(f'\x1b]777;notify;{title};{body}\x07') sys.stdout.flush() notify("Script Complete", "Processing finished") ``` ### Node.js node ``` function notify(title, body) { process.stdout.write(`\x1b]777;notify;${title};${body}\x07`); } notify('Build Done', 'webpack finished'); ``` ### Passthrough tmux Se usi tmux all'interno di cmux, abilita il passthrough: .tmux.conf ``` set -g allow-passthrough on ``` ``` printf '\ePtmux;\e\e]777;notify;Title;Body\a\e\\' ``` Canonical: https://cmux.com/it/docs/notifications Documentation index: https://cmux.com/llms.txt