OSC 99 — Desktop notifications (kitty protocol)

OSC 99 is kitty's structured desktop-notification protocol: OSC 99 ; metadata ; payload ST, where metadata is a list of key=value pairs (i= identifier, d= done flag, p= payload type such as title/body, e= base64-encoded) and payload is the (optionally base64) text. It supports multi-chunk notifications, titles+bodies, actions, and icons — far richer than OSC 9.

frame

OSC introducer: \x1b] ESC ] (0x1B 0x5D)

terminator (ST|BEL): ST \x1b\ · BEL \x07

parameters / subcommands

id	name	bytes (ST)	meaning
simple	Simple notification	\x1b]99;;Hello\x1b\	OSC 99 ; ; <text> ST shows a notification with the given body text (empty metadata = single-chunk, plain).
titled	Title + body	\x1b]99;i=1:p=title;Build\x1b\	OSC 99 ; i=ID : p=title ; <title> ST then OSC 99 ; i=ID : p=body : d=1 ; <body> ST builds a multi-part notification keyed by identifier i.

gotchas

The metadata is colon-separated key=value pairs BEFORE the ';' that introduces the payload; getting the ';' vs ':' separators wrong breaks parsing.
Long or binary payloads should be base64-encoded with e=1; multi-chunk notifications share the same i= identifier and end with d=1.
OSC 99 is far richer than OSC 9 (titles, bodies, actions, icons) but only kitty (and a small set of compatible terminals) implement it — feature-detect.
Notifications can be suppressed by the OS/notification daemon; a successful escape does not guarantee a visible popup.
Over tmux/ssh the sequence needs passthrough.

provenance

source: https://sw.kovidgoyal.net/kitty/desktop-notifications/
version: kitty desktop-notifications protocol documentation, retrieved 2026-05-29
retrieved: 2026-05-29 · updated: 2026-05-29T00:00:00Z

per-fact attribution:

#summary — https://sw.kovidgoyal.net/kitty/desktop-notifications/ kitty: OSC 99 ; <metadata key=value pairs> ; <payload> ST. Metadata keys include i (id), d (done), p (payload type: title/body/...), e (base64 encoding flag), a (actions). Allows multi-chunk title+body notifications.
#adoption — https://github.com/kovidgoyal/kitty/blob/master/docs/desktop-notifications.rst The protocol spec source documents the escape-code grammar and the encoding/chunking rules; published for other terminals to implement.

agent: curl -H 'accept: application/json' wire.phall.io/terminal-osc/99 or /terminal-osc/99.json

OSC 99 — Desktop notifications (kitty protocol)

frame

parameters / subcommands

gotchas

provenance

see also