127 lines
2.7 KiB
Text
127 lines
2.7 KiB
Text
---
|
|
title: Notifications
|
|
description: Desktop notifications in cmux for AI agents
|
|
---
|
|
|
|
# Notifications
|
|
|
|
cmux supports desktop notifications, allowing AI agents and scripts to alert you when they need attention.
|
|
|
|
## How It Works
|
|
|
|
1. A process in the terminal sends an OSC escape sequence
|
|
2. cmux parses the notification title and body
|
|
3. If the terminal isn't focused, a desktop notification appears
|
|
4. The tab shows an unread badge
|
|
|
|
## Sending Notifications
|
|
|
|
### Using the CLI
|
|
|
|
The simplest way to send a notification:
|
|
|
|
```bash
|
|
cmux notify --title "Task Complete" --body "Your build finished"
|
|
```
|
|
|
|
With a subtitle:
|
|
|
|
```bash
|
|
cmux notify --title "Claude Code" --subtitle "Waiting" --body "Agent needs input"
|
|
```
|
|
|
|
### Using OSC Sequences
|
|
|
|
You can send notifications directly using escape sequences:
|
|
|
|
#### OSC 99 (Kitty Protocol)
|
|
|
|
```bash
|
|
# Basic notification
|
|
printf '\e]99;i=1;e=1;d=0:Hello World\e\\'
|
|
|
|
# With title and body
|
|
printf '\e]99;i=1;e=1;d=0;p=title:My Title\e\\'
|
|
printf '\e]99;i=1;e=1;d=0;p=body:Message body here\e\\'
|
|
```
|
|
|
|
#### OSC 777 (RXVT Protocol)
|
|
|
|
```bash
|
|
printf '\e]777;notify;My Title;Message body here\a'
|
|
```
|
|
|
|
See [OSC Sequences](/docs/osc-sequences) for full format documentation.
|
|
|
|
## Notification Behavior
|
|
|
|
### Suppression
|
|
|
|
Notifications are suppressed (no desktop alert) when:
|
|
|
|
- The cmux window is focused
|
|
- The specific tab sending the notification is active
|
|
- The notification panel is open
|
|
|
|
This prevents duplicate alerts when you're already looking at the terminal.
|
|
|
|
### Notification Panel
|
|
|
|
Press **⌘I** to open the notification panel, showing all notifications:
|
|
|
|
- Click a notification to jump to that tab
|
|
- Notifications are marked as read when viewed
|
|
- Clear all with the clear button
|
|
|
|
### Quick Jump
|
|
|
|
Press **⌘⇧U** to jump directly to the tab with the most recent unread notification.
|
|
|
|
## Notification Lifecycle
|
|
|
|
1. **Received** - Notification appears in panel, desktop alert fires (if not suppressed)
|
|
2. **Unread** - Badge shown on tab
|
|
3. **Read** - Cleared when you view that tab
|
|
4. **Cleared** - Removed from panel
|
|
|
|
## Integration Examples
|
|
|
|
### Notify After Long Command
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### Notify When Build Finishes
|
|
|
|
```bash
|
|
npm run build && cmux notify --title "Build Success" --body "Ready to deploy"
|
|
```
|
|
|
|
### Watch Script Completion
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# long-running-task.sh
|
|
|
|
do_work() {
|
|
# ... your task
|
|
sleep 10
|
|
}
|
|
|
|
do_work
|
|
cmux notify --title "Task Complete" --body "long-running-task.sh finished"
|
|
```
|