Notifications and progress¶

Status: Extension, several incompatible origins.

An application that finishes a long job wants to tell the user even when the window is not focused. Terminals expose this through desktop notifications, urgency hints, and, more recently, a progress indicator in the tab or taskbar. No two origins agree on the selector.

Syntax¶

OSC 9: iTerm2 notification¶

OSC 9 ; text ST

Shows text as a desktop notification. Introduced by iTerm2.

OSC 9 collisions: ConEmu¶

ConEmu independently chose selector 9 for a family of sub-commands:

OSC 9 ; 1 ; ms ST                  sleep
OSC 9 ; 2 ; text ST                message box
OSC 9 ; 4 ; state ; progress ST    taskbar progress
OSC 9 ; 9 ; path ST                current directory
OSC 9 ; 10 ST                      ANSI processing toggle

An emulator receiving OSC 9 ; 4 ; 1 ; 50 ST must decide whether it is a notification whose text is 4;1;50 or a 50% progress bar. Windows Terminal and mintty follow ConEmu; iTerm2, kitty, foot, and WezTerm treat OSC 9 as a notification. Applications cannot send one form that is correct everywhere.

OSC 9;4 progress¶

OSC 9 ; 4 ; 0 ST          clear
OSC 9 ; 4 ; 1 ; N ST      normal, N percent (0–100)
OSC 9 ; 4 ; 2 ; N ST      error state
OSC 9 ; 4 ; 3 ST          indeterminate
OSC 9 ; 4 ; 4 ; N ST      paused/warning state

Rendered as a taskbar progress overlay (Windows) or a tab indicator.

OSC 777: rxvt-unicode notify¶

OSC 777 ; notify ; title ; body ST

Originated in the urxvt notify Perl extension and adopted as the most common Linux form. Fields are plain text; ; inside the body is not escapable.

OSC 99: kitty desktop notifications¶

OSC 99 ; key=value : key=value ; payload ST

A structured protocol with identifiers, chunked payloads, icons, urgency, buttons, and a close-and-report mechanism. Common keys:

Key	Meaning
`i=ID`	Notification identifier for updates, closing, and activation reports
`d=0`	More chunks follow (default `d=1`, done)
`p=title` / `p=body` / `p=icon` / `p=buttons`	What the payload is
`e=1`	Payload is base64-encoded
`u=0..2`	Urgency: low, normal, critical
`a=focus,report`	Action on activation
`o=always` / `unfocused` / `invisible`	When to show

On activation the emulator sends OSC 99 ; i=ID ; ST back as input when a=report was requested. Query support with OSC 99 ; i=ID : p=? ST.

BEL and urgency¶

BEL (0x07) remains the lowest common denominator. Emulators map it to an audible bell, a visual flash, an X11 urgency hint, a Wayland activation request, or a tab badge, and most let the user choose. It cannot carry text.

Behavior¶

Whether a notification appears while the window is focused is emulator-defined; kitty and foot default to unfocused only.
Text is shown by the desktop's notification daemon, which may apply its own markup rules; emulators generally strip control bytes but not markup.
Progress states persist until cleared. A program that exits without OSC 9 ; 4 ; 0 leaves a stale bar.
Multiplexers drop all of these without passthrough.

Probe¶

tools/sendosc notify 'TDN' 'notification probe'
printf '\033]9;TDN OSC 9 probe\033\\'
printf '\033]777;notify;TDN;OSC 777 probe\033\\'
printf '\033]99;i=1:d=0:p=title;TDN\033\\'; printf '\033]99;i=1:p=body;OSC 99 probe\033\\'
printf '\033]9;4;1;50\033\\'; sleep 2; printf '\033]9;4;0\033\\'

Unfocus the window before running if the emulator hides focused notifications.

Sources¶

Compatibility¶

Feature support by terminal. Imported claims have not been reverified; unknown is not unsupported.
Feature / stable ID	Alacritty	Apple Terminal	ConPTY (conhost)	Contour	DomTerm	foot	Ghostty	iTerm2	kitty	Konsole	mintty	mlterm	PuTTY	Revenant	RLogin	st	tmux	rxvt-unicode	VTE	wayst	WezTerm	Windows Terminal	xterm	xterm.js
OSC 9 notify `osc-9-notification`	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	Unknown	UnsupportedImported · unverified	Unknown	Unknown	Supported	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	UnsupportedImported · unverified	Unknown	Unknown
OSC 9;4 progress `osc-9-4-progress`	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Supported	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown
OSC 777 notify `osc-777-notification`	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	SupportedImported · unverified	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	Unknown	Supported	Unknown	Unknown	Unknown	Unknown	PartialImported · unverified	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown
OSC 99 `osc-99-notification`	Unknown	Unknown	Unknown	Unknown	Unknown	SupportedImported · unverified	SupportedImported · unverified	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown
BEL urgency/visual `c0-bel-attention`	SupportedImported · unverified	SupportedImported · unverified	Unknown	SupportedImported · unverified	Unknown	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	Unknown	SupportedImported · unverified	Unknown	Unknown	Unknown	SupportedImported · unverified	Unknown	SupportedImported · unverified	Unknown	SupportedImported · unverified	SupportedImported · unverified	SupportedImported · unverified	PartialImported · unverified
ConEmu commands (sleep, message box, progress, directory) `osc-9-conemu-family`	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown	Unknown