OSC 9
OSC 9 sends a desktop notification from the terminal to the operating system's notification system. Originally introduced by ConEmu, this sequence allows command-line applications to alert the user when a long-running task completes or when attention is needed.
Syntax
OSC 9 ; text ST
OSC 9 ; text BEL
OSC9 = 0x1b, "]", "9", ";", text, ( 0x07 | 0x1b, "\\" ) ;
text = character, { character } ;Parameters
| Parameter | Description | Default |
|---|---|---|
text | The notification message text to display | (required) |
Description
Per the ConEmu ANSI codes documentation, OSC 9 triggers a system desktop notification containing the provided text. The notification typically appears as an OS-native notification balloon, toast, or banner depending on the platform.
This is a simple fire-and-forget mechanism with no acknowledgment or response from the terminal. The notification is displayed immediately and follows the OS notification behavior (auto-dismiss, notification center, etc.).
ConEmu extended OSC 9 with additional sub-commands using a semicolon-delimited format:
OSC 9 ; 4 ; st ; pr ST— Progress reporting (see OSC 9;4)OSC 9 ; 9 ; path ST— Set working directory (ConEmu-specific)
Some terminals (notably iTerm2 and Kitty) support OSC 9 for basic desktop notifications but may use different mechanisms for their native notification protocols.
Desktop notification support varies significantly across terminals. Some terminals require user opt-in for security reasons, as malicious terminal output could otherwise spam notifications.
Examples
# Send a simple notification
printf '\e]9;Build complete!\a'
# Notify after a long-running command
make build && printf '\e]9;Build succeeded\a' || printf '\e]9;Build failed!\a'
# Notification with ST terminator
printf '\e]9;Task finished\e\\'
Specifications
| Specification | Section |
|---|---|
| ConEmu ANSI Codes | — |
Terminal support
| Terminal | Support | Version | Notes |
|---|---|---|---|
| Terminal Emulators | |||
| Alacritty | ✗ | No | Not listed in escape_support.md OSC section |
| Bobcat | ✓ | 0.9.0 | WhenMessage callback for desktop notifications added in commit 4a78353 |
| contour | ✓ | v0.6.2.8008 | ConEmu-style notification and progress (OSC 9;4 included) |
| foot | ✓ | Yes | iTerm2/urxvt notify extension, osc.c:1381-1396, 538-590 |
| Ghostty | ✓ | v1.0.0 | |
| iTerm2 | ✓ | v20260216-nightly | ConEmu/iTerm2 desktop notification |
| Kitty | ~ | Yes | Supports legacy iTerm2 OSC 9 notifications |
| Konsole | ✗ | No | ConEmu OSC 9 recognized but only OSC 9;4 (progress) is implemented in src/Vt102Emulation.cpp:1821-1855; simple notification form not implemented |
| mintty | ✗ | No | Not implemented (ConEmu/iTerm2 desktop notification) |
| mlterm | ✗ | No | |
| PuTTY | ✗ | No | Not implemented in do_osc function |
| Rio | ✗ | No | |
| rxvt-unicode | ✗ | No | |
| st | ✗ | No | |
| terminology | ✗ | No | OSC 777 used instead for notifications |
| VT100 | ✗ | No | |
| VTE | ✗ | No | OSC 9 basic notification not implemented, only 9;4 for progress |
| WezTerm | ✓ | Yes | OSC 9 SystemNotification (ConEmu/iTerm2) - see wezterm-escape-parser/src/osc.rs:43,318-350,470 |
| Windows Terminal | ✓ | Yes | ConEmuAction case; handles OSC 9;4 (progress), 9;9 (CWD), 9;12 (mark) |
| xterm | ✗ | No | No evidence in documentation or source code |
| xterm.js | ✗ | No | Not implemented |
| Multiplexers | |||
| cy | ✗ | No | |
| GNU Screen | ✗ | No | |
| tmux | ✗ | No | ConEmu notifications not implemented |
| tuios | ✗ | No | |
| Zellij | ✗ | No | |
See also
- OSC 9;4 — Progress Reporting — Report task progress to the terminal's taskbar
- OSC 777 — Desktop Notification — An alternative notification protocol used by rxvt-unicode and others