f36525f5f1
- Add Fumadocs-based docs site (docs-site/) - Document all features: tabs, notifications, splits, socket API, CLI - Add Claude Code hooks guide with cmuxterm detection - Update README with native macOS emphasis and brew install - Add homebrew-cmuxterm to .gitignore (has its own repo)
204 lines
4 KiB
Text
204 lines
4 KiB
Text
---
|
|
title: OSC Sequences
|
|
description: OSC escape sequence reference for cmuxterm notifications
|
|
---
|
|
|
|
# OSC Sequences
|
|
|
|
cmuxterm supports two OSC (Operating System Command) escape sequence standards for sending notifications from terminal programs.
|
|
|
|
## OSC 99 (Kitty Protocol)
|
|
|
|
The Kitty notification protocol provides rich notification support with multiple parameters.
|
|
|
|
### Format
|
|
|
|
```
|
|
ESC ] 99 ; <params> ; <payload> ESC \
|
|
```
|
|
|
|
Or using BEL terminator:
|
|
|
|
```
|
|
ESC ] 99 ; <params> ; <payload> BEL
|
|
```
|
|
|
|
### Parameters
|
|
|
|
Parameters are semicolon-separated key=value pairs:
|
|
|
|
| Parameter | Description | Values |
|
|
|-----------|-------------|--------|
|
|
| `i` | Notification ID | Any string |
|
|
| `e` | Event type | `1` = new notification |
|
|
| `d` | Done flag | `0` = more data coming, `1` = complete |
|
|
| `p` | Payload type | `title`, `body`, `subtitle` |
|
|
|
|
### Payload
|
|
|
|
After the final semicolon, the payload contains the notification content. If `p=` is specified, the payload is interpreted as that type.
|
|
|
|
### Examples
|
|
|
|
**Simple notification:**
|
|
|
|
```bash
|
|
printf '\e]99;i=1;e=1;d=0:Hello World\e\\'
|
|
```
|
|
|
|
**Notification with title and body:**
|
|
|
|
```bash
|
|
# Set title
|
|
printf '\e]99;i=1;e=1;d=0;p=title:Build Complete\e\\'
|
|
# Set body
|
|
printf '\e]99;i=1;e=1;d=1;p=body:All tests passed\e\\'
|
|
```
|
|
|
|
**With subtitle:**
|
|
|
|
```bash
|
|
printf '\e]99;i=1;e=1;d=0;p=title:Claude Code\e\\'
|
|
printf '\e]99;i=1;e=1;d=0;p=subtitle:Session abc123\e\\'
|
|
printf '\e]99;i=1;e=1;d=1;p=body:Waiting for input\e\\'
|
|
```
|
|
|
|
### Shell Function
|
|
|
|
```bash
|
|
notify_osc99() {
|
|
local title="$1"
|
|
local body="$2"
|
|
local id="${3:-1}"
|
|
|
|
printf '\e]99;i=%s;e=1;d=0;p=title:%s\e\\' "$id" "$title"
|
|
printf '\e]99;i=%s;e=1;d=1;p=body:%s\e\\' "$id" "$body"
|
|
}
|
|
|
|
# Usage
|
|
notify_osc99 "Build Done" "Your project compiled successfully"
|
|
```
|
|
|
|
## OSC 777 (RXVT Protocol)
|
|
|
|
The RXVT/urxvt protocol is simpler, with a fixed format for title and body.
|
|
|
|
### Format
|
|
|
|
```
|
|
ESC ] 777 ; notify ; <title> ; <body> BEL
|
|
```
|
|
|
|
Or with ST terminator:
|
|
|
|
```
|
|
ESC ] 777 ; notify ; <title> ; <body> ESC \
|
|
```
|
|
|
|
### Examples
|
|
|
|
**Basic notification:**
|
|
|
|
```bash
|
|
printf '\e]777;notify;Hello;World\a'
|
|
```
|
|
|
|
**Build completion:**
|
|
|
|
```bash
|
|
printf '\e]777;notify;Build Complete;All 42 tests passed\a'
|
|
```
|
|
|
|
**With ST terminator:**
|
|
|
|
```bash
|
|
printf '\e]777;notify;Task Done;Ready for review\e\\'
|
|
```
|
|
|
|
### Shell Function
|
|
|
|
```bash
|
|
notify_osc777() {
|
|
local title="$1"
|
|
local body="$2"
|
|
printf '\e]777;notify;%s;%s\a' "$title" "$body"
|
|
}
|
|
|
|
# Usage
|
|
notify_osc777 "Download Complete" "File saved to ~/Downloads"
|
|
```
|
|
|
|
## Comparison
|
|
|
|
| Feature | OSC 99 | OSC 777 |
|
|
|---------|--------|---------|
|
|
| Title | ✓ | ✓ |
|
|
| Body | ✓ | ✓ |
|
|
| Subtitle | ✓ | ✗ |
|
|
| Notification ID | ✓ | ✗ |
|
|
| Complexity | Higher | Lower |
|
|
| Compatibility | Kitty, cmuxterm | RXVT, cmuxterm |
|
|
|
|
## Recommendations
|
|
|
|
- **Use OSC 777** for simple title + body notifications
|
|
- **Use OSC 99** when you need subtitles or notification IDs
|
|
- **Use the CLI** (`cmuxterm notify`) for the easiest integration
|
|
|
|
## Testing
|
|
|
|
Test notifications in your terminal:
|
|
|
|
```bash
|
|
# OSC 777 (simpler)
|
|
printf '\e]777;notify;Test;This is a test notification\a'
|
|
|
|
# OSC 99 (with subtitle)
|
|
printf '\e]99;i=test;e=1;d=0;p=title:Test Notification\e\\'
|
|
printf '\e]99;i=test;e=1;d=0;p=subtitle:Subtitle here\e\\'
|
|
printf '\e]99;i=test;e=1;d=1;p=body:This is the body text\e\\'
|
|
```
|
|
|
|
## Integration with Other Tools
|
|
|
|
### tmux
|
|
|
|
If using tmux inside cmuxterm, enable passthrough:
|
|
|
|
```bash
|
|
# In .tmux.conf
|
|
set -g allow-passthrough on
|
|
```
|
|
|
|
Then wrap sequences:
|
|
|
|
```bash
|
|
printf '\ePtmux;\e\e]777;notify;Title;Body\a\e\\'
|
|
```
|
|
|
|
### SSH
|
|
|
|
Notifications work over SSH if your SSH client supports OSC passthrough. Most modern terminals do.
|
|
|
|
### 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
|
|
|
|
```javascript
|
|
function notify(title, body) {
|
|
process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
|
|
}
|
|
|
|
notify('Build Done', 'webpack finished');
|
|
```
|