OSC 7501 is a new terminal escape sequence proposed by Mitchell Hashimoto that lets any program tell the terminal what it is doing: idle, working, waiting on the user, finished, or failed, and why. The protocol emerged from work on the Superlogical and Ghostty projects but is designed as a generic, terminal‑native specification that does not depend on any particular product or language. It addresses the common frustration of long‑running terminal work such as builds, deployments, package upgrades, data processing, and coding agents, where users often lose track of whether a program is still running, blocked on input, or has completed.
The protocol uses the operating system command (OSC) introducer ESC ] 7501 ; followed by colon‑separated key=value pairs and terminated by ESC [[backslash]]. The only required key is state, which can be idle, working, done, blocked, or error. Optional keys include app for a stable machine‑readable program name (e.g., terraform or claude‑code), msg for a single human‑readable line encoded in base64 UTF‑8, and kind to clarify why a program is blocked (permission, question, auth). Programs that manage multiple concurrent activities can report hierarchical IDs separated by slashes—for example, a deploy tool can be working at the root while us‑east/push shows working at 40% progress and eu‑west is blocked waiting for approval. A report whose id does not match the grammar is ignored, and unknown keys are safely skipped, making the protocol robust and extensible.
This image illustrates the OSC 7501 protocol format, which is described in the article as a terminal escape sequence for reporting program status (idle, working, done, blocked, error) with optional keys for app name, message, and block reason.
Because OSC 7501 is emitted via the existing pseudo‑terminal, it works over SSH, inside containers, and anywhere a PTY is available, avoiding the fragility of heuristics that parse window titles or screen contents and eliminating the need for each program to integrate with every separate inbox‑specific API. Compared with the older OSC 9;4 progress indicator, which can only convey busy/not busy, OSC 7501 provides detailed states and messages. Implementations already exist in libghostty, the Rex terminal emulator, and have been added to projects such as Terraform, Claude Code, Codex, and Homebrew via small plugins or forks. While the specification defines the mechanism, it leaves presentation to each terminal, so the exact way status is surfaced—whether as a spinner, icon, or in‑app inbox—remains an open question for developers adopting the standard.