Program status in the terminal
Jazz tells your terminal what it is doing, so you can see at a glance — from another tab — whether a run is working, waiting on you, finished, or failed. Terminals that understand these signals (Ghostty, Rex, and more as the spec spreads) show it as a tab spinner, a “needs you” badge, and a persistent “finished, unviewed” mark that survives the next shell prompt.
Everything is plain escape-sequence output on the controlling terminal. Terminals that do not know a sequence ignore it, so nothing changes if yours does not support it yet.
What gets reported
Jazz’s run state machine already knows its state, so the reports carry it directly — no screen-scraping:
| Jazz state | Reported as |
|---|---|
| Agent thinking or streaming | state=working |
| A tool is running | state=working with the tool name |
| A tool is awaiting approval | state=blocked kind=permission with the approval text |
| A question is waiting | state=blocked kind=question with the question |
| A password/token is being asked | state=blocked kind=auth with the prompt (never the value) |
| A file picker is open | state=blocked kind=question |
| A turn finished | state=done |
A jazz run failed | state=error |
A jazz run parked for a person (--park) | state=blocked with the parked input |
The blocked and error reports also ping the tab using the same terminal notification protocols as desktop notifications (OSC 9, 99, or 777, selected per terminal; tmux passthrough included), so a run parked in another tab flashes or rings as well as showing a badge.
OSC 7501
The primary signal is OSC 7501 (the Program Status Protocol). Jazz emits reports of the form:
ESC ] 7501 ; state=blocked:app=jazz:kind=permission:msg=<base64> STReports are deduplicated: the same state does not re-emit while it holds, and a repeated approval ping for the same ask does not re-ring within a few seconds.
Disable all 7501 reports with JAZZ_OSC7501=0 (also false or off).
Terminal notifications
When a run goes blocked or error, Jazz writes the terminal’s native
notification sequence so the tab gets attention. Protocol selection and the
JAZZ_NOTIFICATIONS_TERMINAL override are shared with the desktop
notifications setting, so off or osc9
applies to both. Notifications only fire for state changes — an idle run does
not ping.
Current working directory
Jazz reports its working directory with OSC 7
at the start of a session and a jazz run. Terminals use it for tab titles and
cwd-aware tooling (tmux, iTerm2). Disable with JAZZ_OSC_CWD=0.
What is not reported yet
- Sub-agent status as separate records. OSC 7501 supports a per-record
id(e.g.subagent/<agentId>), which would let a terminal show each running sub-agent’s own state. The encoder already supportsidandtitle; wiring the per-sub-agent records is the next step. state=clearto explicitly drop the record on cancel — the next shell prompt already resets it in supporting terminals.
Which escape codes Jazz uses
| Code | Purpose | Status |
|---|---|---|
| OSC 7501 | Program status (this page) | New here |
| OSC 9 / 99 / 777 | Terminal notifications | Reused from the desktop notifications stack |
| OSC 7 | Working directory | New here |
| OSC 52 | Clipboard | Already supported (fullscreen interface) |
| OSC 11 | Terminal background query | Already used for theme-aware colors |
| OSC 8 / SGR 8 | Hyperlinks | Not yet emitted; a follow-up for link rendering |
| OSC 133 | Semantic prompt marks | Not applicable — those describe shell prompts, and Jazz is a TUI |