Program status
OpenTUI sends OSC 7501 Program Status Protocol reports. A report tells the terminal what the program is doing. The terminal decides how to show it, for example as a tab indicator, an inbox entry, or a desktop notification.
renderer.setProgramStatus({ state: "working", app: "deploy", message: "Deploying v2.4.1" })
renderer.setProgramStatus({
state: "blocked",
kind: "permission",
app: "deploy",
message: "Approve production deploy?",
})
renderer.setProgramStatus({ state: "done", app: "deploy", message: "Deployed to 3 regions" })States
state | Meaning | Extra fields |
|---|---|---|
idle | At rest and waiting for the next instruction | |
working | Running | progress |
blocked | Waiting for the user | kind, progress |
done | Finished, and the user has not seen the result yet | |
error | Failed and stopped | |
clear | Removes the addressed record and every record beneath it | Accepts only id |
kind is "permission", "question", or "auth". progress is an integer from 0 to 100. Omit progress when the
work has no percentage.
Report idle when the user cancels work. Report done or error before the program exits, so the terminal keeps a
record for the user to find.
Records
Each report replaces its record completely. A field missing from a report is missing from the record afterwards, so
send app and title with every report that needs them.
| Field | Value |
|---|---|
id | Record path such as build/test. Omit it for the root record |
app | Stable program identifier such as cargo. Up to 32 [A-Za-z0-9_.+-] bytes |
title | Short label for the record. Up to 192 UTF-8 bytes |
message | One line that says what the record is doing or waiting for. Up to 2048 bytes |
An id has up to 8 segments separated by /. Each segment has 1 to 32 [A-Za-z0-9_.+-] bytes, and the whole id has
at most 128 bytes. A program that runs several tasks can report one record for each task:
renderer.setProgramStatus({ state: "working", app: "deploy" })
renderer.setProgramStatus({ state: "working", id: "us-east", title: "US East", progress: 40 })
renderer.setProgramStatus({ state: "blocked", kind: "permission", id: "eu-west", title: "EU West" })
renderer.setProgramStatus({ state: "clear", id: "us-east" })title and message cannot contain control characters, including newline and tab. OpenTUI encodes them as base64.
Results
setProgramStatus() returns true when OpenTUI queues the report. It returns false in these cases:
The renderer is destroyed.
The terminal is not active, for example before
setupTerminal()finishes or while the renderer is suspended.The output queue is full.
A report that breaks a rule above throws. OpenTUI checks the whole report before it writes anything.
Detection
Terminals ignore OSC sequences they do not implement, so setProgramStatus() does not wait for detection. OpenTUI
sends the OSC 7501 ; ? query at startup, except when TERM names foot, whose reduced probe omits OSC capability queries.
renderer.capabilities?.program_status becomes true when the terminal replies. A false value can also mean that
the reply has not arrived yet.
renderer.on("capabilities", (capabilities) => {
console.log("program status", capabilities.program_status)
})Lifetime
Records belong to the terminal, not to the renderer. When the process exits or the shell shows a new prompt, the
terminal drops working and blocked records. done and error records stay until the terminal decides to remove
them. OpenTUI does not clear records when the renderer is destroyed or suspended.
Multiplexers
OpenTUI does not wrap reports in tmux or GNU Screen passthrough. A passthrough report would reach the outer terminal, which cannot tell panes apart or see the program exit. A multiplexer that implements OSC 7501 receives reports directly.
Next
Notifications covers one-time desktop notifications.
Terminal capabilities explains query and detection timing.
Renderer documents the renderer and its capability event.