# Agent Status (OSC 9999)

> Report a coding agent's state to Orca, which shows it on a dashboard of every agent it runs.

- **Sequence:** `OSC 9999 ; JSON ST`
- **ECMA-48:** [§8.3.89 OSC – Operating System Command, p. 51](https://archive.org/details/ecma-48-5th-edition-june-1991/page/n64/mode/1up)
- **Specification:** [agent-status-osc.ts, Orca source](https://github.com/stablyai/orca/blob/e705cac04a1db7e7e2184746e912142d34ca838b/src/shared/agent-status-osc.ts#L5)

`OSC 9999` is Orca's. Orca, by Stably AI, is not a terminal but a desktop
app for running many coding agents side by side, each in a terminal pane
built on xterm.js, and an agent uses this sequence to tell it what state it
is in. Orca shows that on its dashboard, putting a `blocked` agent among
those that need the user.

The body is one JSON object. Its `state` must be `working`, `blocked`,
`waiting` or `done`, or the whole report is rejected. Optional fields add
the kind of agent, the prompt it was given, the model, the tool it is using
and that tool's input, the question it is waiting on, and its last message,
each cut to a length Orca sets; `interrupted` and `sessionBoundary` go with
`done`. Orca reads the sequence out of every pane's output before the
terminal sees it, and nothing is sent back
([`agent-status-osc.ts`](https://github.com/stablyai/orca/blob/e705cac04a1db7e7e2184746e912142d34ca838b/src/shared/agent-status-osc.ts#L5),
[`agent-status-types.ts`](https://github.com/stablyai/orca/blob/e705cac04a1db7e7e2184746e912142d34ca838b/src/shared/agent-status-types.ts#L51)).

Orca has not documented it: an
[issue asking for documentation](https://github.com/stablyai/orca/issues/14033)
is open, a pull request that would have added it was closed unmerged, and
that draft called the format an internal contract, not a public interface.
This page describes the source at Orca 1.4.219. The
[Program Status Protocol](https://control-codes.page/proposals/osc-7501/index.html.md) proposal names it as earlier
work on the same idea.

A default xterm has no `OSC 9999` and ignores it
([the OSC numbers it knows](https://github.com/ThomasDickey/xterm-snapshots/blob/xterm-411a/misc.c#L3476-L3504)).
The cases follow xterm.

libghostty-vt does not recognize `OSC 9999` either: its OSC parser in
`osc.zig` has no state for the number, so the string is dropped, and the
cases pass.

## Support

| Terminal | Version | Support | Notes |
| --- | --- | --- | --- |
| VT220 | [manual](https://vt100.net/docs/vt220-rm/), 2nd ed., 1984 | No | OSC is not among the controls it recognizes ([§4.2](https://vt100.net/docs/vt220-rm/chapter4.html#S4.2)) |
| VT510 | [manual](https://vt100.net/docs/vt510-rm/), 1st ed., 1993 | No | ignores an OSC string ([chapter 4](https://vt100.net/docs/vt510-rm/chapter4.html)) |
| xterm | patch 412, [xterm-411a](https://github.com/ThomasDickey/xterm-snapshots/tree/xterm-411a) | No | ignored |
| libghostty-vt | [83edd49](https://github.com/ghostty-org/ghostty/tree/83edd491e3024ae5e50393d62877b8897da1cccd) | No | ignored |
| Konsole | 26.11.70, [a24c3d71](https://invent.kde.org/utilities/konsole/-/tree/a24c3d71be3684f24d030aa2dbe9bd723d985233) | No | not among the OSC numbers it handles ([`Vt102Emulation.h`](https://invent.kde.org/utilities/konsole/-/blob/a24c3d71be3684f24d030aa2dbe9bd723d985233/src/Vt102Emulation.h#L189-L205)) |
| ConEmu | build 230724, its [documentation](https://conemu.github.io/en/AnsiEscapeCodes.html) | No | not in its [ANSI escape codes](https://conemu.github.io/en/AnsiEscapeCodes.html) |
| Orca | 1.4.219, [source](https://github.com/stablyai/orca/tree/e705cac04a1db7e7e2184746e912142d34ca838b) | Yes | read from each pane's output; nothing is sent back ([`agent-status-osc.ts`](https://github.com/stablyai/orca/blob/e705cac04a1db7e7e2184746e912142d34ca838b/src/shared/agent-status-osc.ts#L5)) |

## Validation

### OSC9999-1: Nothing on screen

Input, one step per line:

```text
A
\e]9999;{"state":"working","agentType":"example"}\a
B
```

Expected screen:

```text
|AB____|
cursor 1,3
reply none
```

---

This is the Markdown version of <https://control-codes.page/osc/agent-status/>. On that page every validation case runs live in libghostty-vt, the terminal emulation core of Ghostty, compiled to WebAssembly.

The validation cases are written in the notation described in <https://control-codes.page/notation/index.html.md>.