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]9;4;<state>;<percent>\x07\033]9;4;<state>;<percent>\007\e]9;4;<state>;<percent>\aESC ] 9 ; 4 ; STATE ; N BEL1b 5d 39 3b 34 3b ... 3b ... 07Description
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
# 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 successimport 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")// 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);Used in
Real-world tools that emit this sequence — anchors the bytes to commands you've already used.
- winget installemits `\x1b]9;4;1;<percent>\x07` so Windows Terminal paints a green progress segment in the taskbar icon — install completion is glanceable from the taskbar without focus
- PowerShell Write-Progressmodern PSReadLine bridges `Write-Progress` to OSC 9;4 — progress bars in pwsh scripts surface as taskbar progress on Windows Terminal automatically
- npm, pnpm, yarn install progressNode terminal libs (`npmlog`, `gauge`) optionally emit OSC 9;4 when `COLORTERM` indicates Windows Terminal — long installs paint taskbar progress alongside the inline percentage line
- robocopy /tee, MSBuild publishrobocopy's `/tee` pipe and MSBuild publish targets both wrap progress in OSC 9;4 on recent Win11 builds — copy or build completion shows in taskbar even when the prompt is backgrounded
- ConEmu, Cmder (origin of OSC 9;4)ConEmu invented the `\x1b]9;4;<state>;<value>\x07` family — Microsoft adopted it verbatim for Windows Terminal compatibility, so any tool written for ConEmu's progress API works in WT unchanged
Frequently asked
Short answers to the questions developers actually search for this sequence.
- Which terminals actually display
OSC 9;4progress and how does it look? - Windows Terminal (1.20+), ConEmu, and recent WezTerm render OSC 9;4 as a taskbar / tab progress indicator — Windows draws a bar in the taskbar button, WezTerm in the tab title. iTerm2 has a separate proprietary form (
OSC 1337;). Linux terminals (gnome-terminal, konsole, xterm) and macOS Terminal.app ignore OSC 9;4 entirely. There is no portable progress sequence — feature-detect via\x1b]9;4;0;0\x07(clear state) + a known query like XTVERSION and gate the emission, or fall through to a TTY-level progress bar. - What do the state values 0–4 in
OSC 9;4;state;percentmean? - 0 = clear / no progress (hide the indicator); 1 = normal progress (use the
percentvalue); 2 = error (red bar atpercent); 3 = indeterminate / spinner (no percentage); 4 = warning / paused (yellow bar atpercent). Windows Terminal honours all five; ConEmu treats 4 the same as 1. Always end your run with state 0 — leaving a 100% bar visible after the process exits is a common UX bug.
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
- partial
- 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 | partial | no |
Related sequences
In the family cookbook
OSC cookbook · 6. Inline images & progress — `OSC 1337` and `OSC 9 ; 4`