OSC 9 ; 4 Progress Report
Show a program's progress in the tab and the taskbar.
OSC 9 ; 4 ; Ps ; Pn ST
- ECMA-48
- §8.3.89 OSC – Operating System Command, p. 51
- Specification
- ConEmu specific OSC, ConEmu's ANSI escape codes
OSC 9 ; 4 ; Ps ; Pn ST reports how far along a long-running program is, so that the terminal can show it: ConEmu, on Windows, shows it on the taskbar button and in its title, and terminals that have taken it up show it in the tab or the window. Package managers, build tools and installers send it. Ps is the state and Pn a percentage:
Ps | State | Pn |
|---|---|---|
0 | remove the progress indicator | |
1 | in progress, Pn percent done | 0 to 100 |
2 | failed | optional |
3 | in progress, but how far is unknown | |
4 | paused | optional |
It is one of a set of commands ConEmu put under OSC 9, each a number after the 9. Their definition is the ConEmu specific OSC table in ConEmu’s documentation:
| Sequence | Does | libghostty-vt |
|---|---|---|
OSC 9 ; 1 ; ms ST | sleep for ms milliseconds | ignored |
OSC 9 ; 2 ; "text" ST | show a message box | ignored |
OSC 9 ; 3 ; "text" ST | set the tab’s title; empty restores it | ignored |
OSC 9 ; 4 ; Ps ; Pn ST | progress, this page | passed to the host |
OSC 9 ; 5 ST | wait for Enter, Space or Esc | ignored |
OSC 9 ; 6 ; "macro" ST | run a ConEmu GuiMacro | ignored |
OSC 9 ; 7 ; "cmd" ST | run a process | ignored |
OSC 9 ; 8 ; "env" ST | write out an environment variable | ignored |
OSC 9 ; 9 ; "dir" ST | report the shell’s working directory | kept, as OSC 7 |
OSC 9 ; 10 ; n ST | turn ConEmu’s xterm keyboard and output emulation on or off | ignored |
OSC 9 ; 11 ; "text" ST | a comment | ignored |
OSC 9 ; 12 ST | mark the cursor’s position as the start of a prompt | marked, as OSC 133 |
iTerm2 uses OSC 9 ; text ST for a notification, so a terminal that has both tells them apart by what follows the 9: one of ConEmu’s numbers and a ;, or anything else.
Each has a page of its own. A default xterm has none of them, and ignores all of OSC 9 (the OSC numbers it knows). The cases follow xterm.
libghostty-vt passes a progress report to its host through the PROGRESS_REPORT callback, as a state and a percentage, clamping the percentage to 100 and leaving it out for the states that have none; the runner records them, and a case’s progress line checks them. Ghostty, for instance, shows the progress in its tab. The cases where it reports progress that xterm does not are known differences.
Validation
PROGRESS-1: Progress changes nothing on screen
A
\e]9;4;1;50\a # 50%
B
|AB____|
cursor 1,3
reply none
PROGRESS-2: A default xterm reports no progress
\e]9;4;1;50\a
|______|
progress none
PROGRESS-3: Through each state
\e]9;4;1;25\a # in progress
\e]9;4;4;60\a # paused
\e]9;4;2\a # failed
\e]9;4;3\a # unknown
\e]9;4;0\a # remove
|______|
progress none