OSC 9 ; 4 — ConEmu progress indicator (Windows Terminal / Ghostty)

Push live progress percentages / paused / error states to the taskbar or tab icon — the ConEmu protocol that Windows Terminal 1.18+ standardised.

Byte forms

Every common string-literal form so you can paste-and-search either direction.

\\x1b[\x1b]9;4;<state>;<percent>\x07

\\033[\033]9;4;<state>;<percent>\007

\\e[\e]9;4;<state>;<percent>\a

ESC [ESC ] 9 ; 4 ; STATE ; N BEL

hex1b 5d 39 3b 34 3b ... 3b ... 07

Description

ConEmu's progress-bar repurpose of OSC 9 — distinct from iTerm2's `OSC 9 ; <message>` notification (slug `osc-notification`); the `;4` second token is the disambiguator. The terminal forwards progress state to whatever ambient UI it owns: Windows Terminal updates the taskbar icon (Windows 11 unified-progress UX), Ghostty / WezTerm tint the tab indicator, ConEmu paints a horizontal bar across the title bar. Four states (passed as the first numeric after `;4;`): - **`0`** — Remove / clear progress (the explicit reset). - **`1`** — Normal progress, `<percent>` 0–100 — the default linear-progress bar. - **`2`** — Error state, `<percent>` 0–100 — turns the bar red, used for build failures with progress information. - **`3`** — Indeterminate — `<percent>` ignored; renders an indeterminate spinner / barber-pole. - **`4`** — Warning / paused, `<percent>` 0–100 — yellow. Usage pattern: long-running CLI commands (`docker pull`, `cargo build`, `ffmpeg` transcodes, `apt`-style installers) emit `OSC 9 ; 4 ; 1 ; <pct>` after each meaningful step, and `OSC 9 ; 4 ; 0` on success. On failure: `OSC 9 ; 4 ; 2 ; <last-pct>` then optionally `0` after the user acks. Unsupported terminals silently drop the bytes — emit unconditionally. Critical detail: the `\x1b]9;` prefix collides with iTerm2's notification OSC 9; almost every emulator that implements both keys the disambiguation off `;4` being present, so emit the **full** `\x1b]9;4;<state>;<pct>\x07` shape — never abbreviate.

Spec citation: ConEmu OSC 9;4 / Windows Terminal 1.18+ / Ghostty

Parameters

state	0 remove, 1 normal, 2 error, 3 indeterminate, 4 warning/paused.
percent	0–100 integer (ignored when state=3 indeterminate; required for 1/2/4).

Examples

bash

# Build-progress wrapper:\nfor pct in 10 30 60 90; do\n  make step-$pct\n  printf '\033]9;4;1;%d\007' "$pct"\ndone\nprintf '\033]9;4;0\007'   # clear on success

python

import sys, time\nfor pct in range(0, 101, 5):\n    sys.stdout.write(f'\x1b]9;4;1;{pct}\x07'); sys.stdout.flush()\n    time.sleep(0.05)\nsys.stdout.write('\x1b]9;4;0\x07')

// Indeterminate while waiting on the network:\nfmt.Print("\x1b]9;4;3\x07")\ndoSlowFetch()\nfmt.Print("\x1b]9;4;0\x07")

javascript

// Error red-bar at 50%:\nprocess.stdout.write('\x1b]9;4;2;50\x07')

/* Warning / paused state at 75%: */\nprintf("\x1b]9;4;4;75\x07"); fflush(stdout);

Terminal support

xterm: no
Linux console (fbcon): no
macOS Terminal.app: no
iTerm2: no
Windows Terminal: yes
cmd.exe / ConPTY: no
kitty: partial
alacritty: no
WezTerm: yes
Ghostty: yes
GNOME Terminal: no
Konsole: no
tmux: no
GNU screen: no

xterm	Linux console (fbcon)	macOS Terminal.app	iTerm2	Windows Terminal	cmd.exe / ConPTY	kitty	alacritty	WezTerm	Ghostty	GNOME Terminal	Konsole	tmux	GNU screen
no	no	no	no	yes	no	partial	no	yes	yes	no	no	no	no

Related sequences

In the family cookbook

OSC cookbook · 6. Inline images & progress — `OSC 1337` and `OSC 9 ; 4`