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