A Terminal Protocol for Program Status (OSC 7501)

A new terminal escape sequence, OSC 7501, known as the Program Status Protocol, has been specified by the author. This protocol enables any program to inform the terminal about its current status, such as idle, working, waiting for user input, finished, or failed, along with the reason for the status. To illustrate, Terraform can use this protocol to indicate that it is waiting for user input, displaying the message "Apply 3 to add, 1 to change, 0 to destroy?" (base64-encoded).

The author argues that existing solutions for conveying program status in terminals are inadequate, particularly for long-running tasks like builds, deployments, package upgrades, data processing, and coding agents. These tasks often alternate between working on their own, waiting for user input, and finishing, while users typically continue with other activities and need updates on the progress or if their input is required.

The author proposes that existing terminal-native mechanisms, such as monitoring active foreground processes or waiting for periods of quiet output, are insufficient. The Program Status Protocol aims to provide a comprehensive, interaction-agnostic, and generic solution to this problem, addressing issues like progress indication, blocking, completion, and task hierarchies. The author also notes that the problem extends beyond AI and LLMs, applying to various long-running agents.

Examples of existing tools that address part of this problem include agentic inboxes like Herdr, cmux, and Agent Deck. These tools employ various methods, such as heuristics based on screen patterns or out-of-band API reports from individual programs. However, these approaches have limitations, including reliance on heuristics, program-specific integrations, and the inability to work seamlessly across different environments like SSH or containers.

The author believes that OSC 7501 offers a terminal-native solution to these challenges. By allowing programs to report their own status directly through the pseudo-terminal (pty) they already use, the protocol employs a well-behaved, standardized format that is safe to send everywhere. The body of the sequence consists of key=value pairs separated by colons, with the 'state' key being mandatory (indicating one of the defined statuses) and optional keys for additional information like the program name and a human-readable message.

The author provides an example of integrating this protocol into a shell script to wrap rsync, demonstrating the ease of implementation without requiring SDKs, sockets, environment variables, JSON, or bias towards specific workloads or GUI presentations.