# Benachrichtigungen

cmux unterstützt Desktop-Benachrichtigungen, mit denen KI-Agenten und Skripte Sie benachrichtigen können, wenn sie Aufmerksamkeit benötigen.

## Lebenszyklus

1.  Empfangen: Benachrichtigung erscheint im Panel, Desktop-Alarm wird ausgelöst (falls nicht unterdrückt)
2.  Ungelesen: Badge wird auf dem Workspace-Tab angezeigt
3.  Gelesen: Wird gelöscht, wenn Sie den Workspace anzeigen
4.  Gelöscht: Aus dem Panel entfernt

### Unterdrückung

Desktop-Alarme werden unterdrückt, wenn:

-   Das cmux-Fenster fokussiert ist
-   Der spezifische Workspace, der die Benachrichtigung sendet, aktiv ist
-   Das Benachrichtigungspanel geöffnet ist

### Benachrichtigungspanel

Drücken Sie `⌘⇧I`, um das Benachrichtigungspanel zu öffnen. Klicken Sie auf eine Benachrichtigung, um zu diesem Workspace zu springen. Drücken Sie `⌘⇧U`, um direkt zum Workspace mit der neuesten ungelesenen Benachrichtigung zu springen.

## Benutzerdefinierter Befehl

Führen Sie jedes Mal einen Shell-Befehl aus, wenn eine Benachrichtigung geplant wird. Setzen Sie ihn unter Einstellungen > App > Benachrichtigungsbefehl. Der Befehl wird über /bin/sh -c mit diesen Umgebungsvariablen ausgeführt:

| Variable | Beschreibung |
| --- | --- |
| `CMUX_NOTIFICATION_TITLE` | Benachrichtigungstitel (Workspace-Name oder App-Name) |
| `CMUX_NOTIFICATION_SUBTITLE` | Benachrichtigungs-Untertitel |
| `CMUX_NOTIFICATION_BODY` | Benachrichtigungstext |

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
```

Der Befehl läuft unabhängig von der System-Soundauswahl. Setzen Sie die Auswahl auf "Ohne", um nur den benutzerdefinierten Befehl zu verwenden, oder behalten Sie beides für einen Systemsound plus eine benutzerdefinierte Aktion bei.

## Benachrichtigungs-Hooks

`cmux.json` kann Benachrichtigungs-Hooks definieren, die jede Benachrichtigungsrichtlinie als JSON über stdin erhalten. Jeder Hook gibt JSON über stdout zurück. Hooks sind standardmäßig deaktiviert; cmux führt sie nur aus, wenn `notifications.hooks` mindestens einen aktivierten Hook enthält. cmux übernimmt den zurückgegebenen Text und die Effekte, sodass Hooks Banner filtern, den Verlauf in der Seitenleiste behalten oder überspringen, Sounds ausführen oder spätere Hooks stoppen können.

cmux.json

```
{
  "notifications": {
    "hooks": [
      {
        "id": "quiet-docs",
        "command": "sed 's/"desktop":true/"desktop":false/'",
        "timeoutSeconds": 20
      }
    ]
  }
}
```

Hook-Eingabe und -Ausgabe

```
{
  "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
  }
}
```

Hooks werden aus der globalen Datei `~/.config/cmux/cmux.json` und aus Projektdateien `.cmux/cmux.json` von übergeordneten Ordnern bis zum aktuellen Workspace geerbt. Projekt-Hooks verwenden vor dem Ausführen denselben Vertrauensdialog wie andere Projektbefehle in `cmux.json`. Feed-Freigabebanner laufen ebenfalls durch diese Hooks. Wenn `desktop` deaktiviert ist, wird das native Banner unterdrückt, während der Feed-Eintrag in cmux verfügbar bleibt. Setze `notifications.hooksMode` in einer Projektkonfiguration auf `replace`, um geerbte Hooks zu ignorieren. Wenn ein Hook fehlschlägt, abläuft oder ungültiges JSON zurückgibt, verwendet cmux das Standardverhalten und zeigt eine Hook-Fehlerwarnung.

### 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.

## Benachrichtigungen senden

### CLI

```
cmux notify --title "Task Complete" --body "Your build finished"
cmux notify --title "Claude Code" --subtitle "Waiting" --body "Agent needs input"
```

### OSC 777 (einfach)

Das RXVT-Protokoll verwendet ein festes Format mit Titel und Inhalt:

```
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 (erweitert)

Das Kitty-Protokoll unterstützt Untertitel und Benachrichtigungs-IDs:

```
# Format: ESC ] 99 ; <params> ; <payload> 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\\'
```

| Funktion | OSC 99 | OSC 777 |
| --- | --- | --- |
| Titel + Text | Ja | Ja |
| Untertitel | Ja | Nein |
| Benachrichtigungs-ID | Ja | Nein |
| Komplexität | Höher | Niedriger |

Verwenden Sie OSC 777 für einfache Benachrichtigungen. Verwenden Sie OSC 99, wenn Sie Untertitel oder Benachrichtigungs-IDs benötigen. Verwenden Sie die CLI (cmux notify) für die einfachste Integration.

## Claude Code Hooks

cmux integriert sich mit [Claude Code](https://docs.anthropic.com/en/docs/claude-code) über Hooks, um Sie zu benachrichtigen, wenn Aufgaben abgeschlossen sind.

### 1\. Hook-Skript erstellen

~/.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\. Claude Code konfigurieren

~/.claude/settings.json

```
{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/cmux-notify.sh" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/cmux-notify.sh" }]
      }
    ]
  }
}
```

Starten Sie Claude Code neu, um die Hooks zu aktivieren.

## GitHub Copilot CLI

Copilot CLI unterstützt [Hooks](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks), die Shell-Befehle bei Lebenszyklus-Ereignissen wie Prompt-Übermittlung, Agent-Stopp und Fehlern ausführen.

~/.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
      }
    ]
  }
}
```

Für Hooks auf Repository-Ebene erstellen Sie eine .github/hooks/notify.json-Datei mit der gleichen Struktur:

.github/hooks/notify.json

```
{
  "version": 1,
  "hooks": {
    "userPromptSubmitted": [ ... ],
    "agentStop": [ ... ]
  }
}
```

## Integrationsbeispiele

### Benachrichtigung nach langem Befehl

~/.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');
```

### tmux Passthrough

Wenn Sie tmux innerhalb von cmux verwenden, aktivieren Sie Passthrough:

.tmux.conf

```
set -g allow-passthrough on
```

```
printf '\ePtmux;\e\e]777;notify;Title;Body\a\e\\'
```

Canonical: https://cmux.com/de/docs/notifications

Documentation index: https://cmux.com/llms.txt