 |
libghostty
|
|
libghostty
|
#include <ghostty/vt/terminal.h>
Data Fields | |
| size_t | size |
| GhosttyProgramStatusState | state |
| GhosttyProgramStatusKind | kind |
| int8_t | progress |
| GhosttyString | id |
| GhosttyString | app |
| GhosttyString | title |
| GhosttyString | message |
A program status report (OSC 7501).
The program status protocol lets a program tell the terminal what it is doing: idle, working, done, waiting on the user, or failed, and why. It is meant for long-running work like builds, deploys, and coding agents, where the user is often looking at something else and wants to know when the work finishes or needs them. The protocol only describes state. How to show it, if at all, is up to your application.
The full specification is at https://www.superlogical.com/rex/docs/build/program-status
For example, a program waiting for the user to approve a change sends this, where ST is the string terminator (ESC \ or BEL):
The callback then receives a report with:
Only reports that pass every check in the specification reach the callback. Text that the program didn't send is an empty string (len=0), never NULL. All strings are only valid during the callback, so copy any you want to keep.
This is a sized struct. Later versions may add fields at the end, and size tells you which fields are present. Every field below has been present since this struct was introduced.
Definition at line 1268 of file terminal.h.
| GhosttyString app |
A stable name for the program that a machine can match on, such as "cargo", "terraform", or "claude-code". Use it as a key for grouping, filtering, or choosing an icon. It is not a label. The label is title. Empty when the report didn't include one. See GhosttyTerminalProgramStatusFn for how an empty app is filled in from a parent record.
Definition at line 1304 of file terminal.h.
Which record this report is about. Empty for the root record.
A program that only reports on itself leaves this empty. A program that reports on several things at once gives each its own id, such as "us-east" and "eu-west" for a deploy to two regions. A "/" makes one record the child of another, so "build/test" is a child of "build". The parent record doesn't have to exist.
Definition at line 1296 of file terminal.h.
What the program needs from the user. Only set for GHOSTTY_PROGRAM_STATUS_STATE_BLOCKED. It is GHOSTTY_PROGRAM_STATUS_KIND_NONE for other states, when the program didn't say, or when it sent a kind this version doesn't know.
Definition at line 1279 of file terminal.h.
| GhosttyString message |
One line of text for people, saying what the record is doing, waiting for, or has finished. You may shorten it to fit, but don't try to read meaning into it.
Definition at line 1313 of file terminal.h.
| int8_t progress |
How far along the work is, from 0 through 100, or -1 when there is no percentage. Only set for GHOSTTY_PROGRAM_STATUS_STATE_WORKING and GHOSTTY_PROGRAM_STATUS_STATE_BLOCKED. For those states, -1 means the work is indeterminate: the program is busy but has no percentage to report. It is also -1 for other states and when the program sent a value outside that range.
Definition at line 1287 of file terminal.h.
| size_t size |
Size of this struct in bytes.
Definition at line 1270 of file terminal.h.
What the program is doing.
Definition at line 1273 of file terminal.h.
| GhosttyString title |
A short label for the record, meant for people. Programs that report several records use this to tell them apart.
Definition at line 1308 of file terminal.h.
1.18.0