Program status: OSC 7501

Status is more than a notification#

Harness reads OSC 7501 revision 0.2 from terminal output. A report can update a pane’s tab, session row, and waiting queue. The daemon scans the output even when no GUI window is open; the GUI parser uses the same report model.

An explicit report takes precedence over inferred agent activity. Use it when your program knows whether it is processing, asking permission, or finished.

Send a minimal report#

A sequence starts with ESC ] 7501 ; and ends with ESC followed by a backslash. The examples below report to the terminal in which the script runs:

printf '\033]7501;state=working:app=my-tool\033\\'
# After work completes:
printf '\033]7501;state=done:app=my-tool\033\\'

The stored states are idle, working, done, blocked, and error. clear removes a record instead of becoming a stored state. blocked can include kind=permission, kind=question, or kind=auth.

Choose the fields you need#

Pairs are separated with colons. Invalid base64 or decoded control characters discard the report. The entire sequence is limited to 4096 bytes; individual fields have smaller limits. Read the protocol reference below before building an encoder.

Understand lifetimes and clearing#

There is no heartbeat. Process exit or an OSC 133 shell-prompt mark clears working and blocked records. done and error remain until the pane receives focus and a keypress. idle persists until explicitly cleared or reset.

printf '\033]7501;state=clear\033\\'

A clear without an ID removes all records; one with an ID removes that record and its descendants. Full terminal reset clears status, but changing the alternate screen does not.

Inspect and subscribe#

harness-cli api call pane.program_status --args '{}'
harness-cli events --follow --json

Program-status events are terminal.program_status and terminal.program_status_removed. The first command uses the calling or active pane; consult api describe pane.program_status when targeting another pane.