I wrote a specification for a new terminal escape sequence:\nOSC 7501, the Program Status Protocol.\nIt lets any program tell the terminal what it's doing: idle, working,\nwaiting on the user, finished, or failed, and why.
\nFor example, here is how Terraform\ncould indicate that it is blocked waiting for user input, with the\nmessage "Apply 3 to add, 1 to change, 0 to destroy?" (base64-encoded). A terminal (or any\nother tool running Terraform) could show this information however it feels\nappropriate: a notification, an inbox, a status icon, etc.
\nESC ] 7501 ; state=blocked:kind=permission:app=terraform:msg=QXBwbHkgMyB0byBhZGQsIDEgdG8gY2hhbmdlLCAwIHRvIGRlc3Ryb3k/ ESC \\\nThis post covers why I think this protocol needs to exist, why the existing approaches aren't good enough (especially for coding agents), and how the protocol works.
This is a completely generic, terminal-native specification and protocol.\nIt emerged from my work on Superlogical and\nGhostty but the specification has no product-specific\nfunctionality or language. It is designed as an idiomatic, well-formed\nspecification that any terminal developer will find familiar.
\nLong-running work is common in terminals: builds, deployments, package upgrades, data processing, and, more and more today, coding agents. These programs alternate between working on their own, waiting on the user, and finishing. Meanwhile, users usually go off and do something else and want to know when the work finishes or needs them.
\nAspects of this problem have been solved in various ways going back decades.\nFor example, some terminals monitor the active foreground process and have\nfeatures to notify when it changes. Or, they wait for some time period of\n"quiet" (for various definitions) output. The specification\nalso lists the reasons why existing sequences aren't enough.
\nUltimately, I felt there wasn't a cohesive, interaction-agnostic, generic solution to this problem that conveyed progress, blocking, completion, and trees of tasks. And it wasn't possible to cobble together pre-existing sequences to achieve it robustly, either.
\nDon't care about AI, LLMs, etc.? Skip this section. The problem\nis generic and applies in a compelling way without bringing in\nAI. It's particularly nasty with AI so I want to call it out, but if you\ndon't care about any of that, just skip this.
\nIt's now increasingly common for people to run many long-running agents for any number of reasons: background research, issue monitoring, bug fixing, large features, etc. Each one works for a while and then stops to ask for permission, ask a question, or report it's done.
\nFrom this, a new category of tool has emerged that I'll simply call\nthe agentic inbox: a single view across every running agent showing\nwhich are working, which are done, and which are waiting on you.\nHerdr, cmux, and\nAgent Deck are a few examples\nof hundreds.
\nWithout a dedicated protocol, they solve the agent status problem in two ways: heuristics and non-terminal APIs.
\nThe first approach is to guess by reading the screen or the window title and matching it against known patterns.
\nHerdr is a good example because it does this well and documents it\nopenly. Its detection manifests\nare TOML rules that classify an agent as idle, working, or blocked. Here is\nthe first of 16 rules\nfor Claude Code:
\n[[rules]]\nid = "osc_title_working"\nstate = "working"\npriority = 1100\nregion = "osc_title"\nvisible_working = true\n# Braille covers <= 2.1.227; half-circles are the 2.1.228 busy spinner.\nregex = ['^[\\x{2800}-\\x{28FF}\\x{25D0}-\\x{25D3}] ']Claude Code is considered "working" if its window title starts with a\nBraille spinner character or, as of version 2.1.228, a half-circle one.\nThe history of that file\nshows ten changes in three months for just Claude Code.
\nThis isn't a criticism of Herdr. Its maintainers are doing the best\npossible job with the tools available. But it demonstrates well the\nbenefit a unified protocol would have.
\nThe second approach is to have the program report its own state through\nan inbox-specific, out-of-band API such as\nHerdr's socket API\nor cmux notify. This is better\nthan heuristics in some ways, because the program that actually knows its state is the\none reporting it. But every program has to integrate with every inbox\nseparately, and a local socket doesn't work over SSH or from within a\ncontainer without extra bridging. The pty already works across all of this.
OSC 7501 is a terminal native answer to this problem. The program\nreports its own state directly via the pty that it always has, using a\nformat that is safe to send everywhere (well-behaved terminals ignore\nunknown OSCs).
\nThe body of the sequence is a list of key=value pairs separated by :.\nThe only required key is state, which is one of:
state | Meaning |
|---|---|
idle | At rest, waiting for the user's next instruction. |
working | Running. May include a progress percentage. |
done | Finished. The result is ready and the user hasn't seen it yet. |
blocked | Can't continue until the user does something. kind says what (permission ,question , orauth ) andmsg says why. |
error | Failed and stopped. |
Optional keys include app, a stable\nmachine-readable program name like cargo or claude-code, and msg,\na single human-readable line encoded as base64.
Programs that run several things at once can report multiple records\nusing hierarchical ids. A deploy tool\ncan be working at the root while\nus-east pushes an image at 40% and eu-west is blocked waiting for\napproval to deploy to production. Both are true at the same time, and\nthe terminal decides what to show. A clear state removes records.
Here's a complete integration for a shell script to wrap rsync\nto participate in this protocol:
status() {\n printf '\\e]7501;state=%s:msg=%s\\e\\\\' "$1" "$(printf '%s' "$2" | base64 | tr -d '\\n')"\n}\nstatus working "Syncing photos"\nrsync -a ~/Photos backup:/photos && status done "Photos synced" || status error "rsync failed"Trivial to script with plain old POSIX sh.\nNo SDK, no sockets, no environment variables, no JSON.\nNo bias towards specific GUI presentations. No bias to any specific\nworkload (like AI). A well-formed, generic foundation to build functionality\nabove that anyone and everyone can participate with.
The full spec\ncovers the rest: record lifetime,\nfeature detection,\nterminfo, size limits,\nand security. It's short. I wrote it all by hand. Please read it.
\nI wrote this specification based on my experience maintaining a terminal\nemulator for many years now. It is written in a way that is easy for\napplication developers to emit, and easy for terminal emulators to consume\nand parse.
\nI've already implemented this protocol twice. We have one implementation\nin libghostty and\nI have a parallel implementation in Rex.\nI've also implemented it as a proof-of-concept in Terraform, Claude Code,\nCodex, and Homebrew via either plugins or forks. In each case, the\nimplementation was no more than a dozen lines.
\nI've been in contact with the maintainers of many popular terminal programs and emulators and they've helped review and shape the specification. But if you have any more feedback, I'm happy to hear it.
\nIf you've implemented the specification please let me know via\nemail (mail icon in the footer) and I'll add you to the list of tools\nthat implement this. Thank you.
\nI'd like us all to stop guessing what programs are doing by reading their screens or process trees. The program already knows. Let's give it a way to tell us!
","headings":[{"level":1,"text":"A Terminal Protocol for Program Status (OSC 7501)","id":"a-terminal-protocol-for-program-status-osc-7501"},{"level":2,"text":"The Problem","id":"the-problem"},{"level":2,"text":"Singling Out \"Agentic Inboxes\"","id":"singling-out-agentic-inboxes"},{"level":3,"text":"Heuristics","id":"heuristics"},{"level":3,"text":"Non-Terminal APIs","id":"non-terminal-apis"},{"level":2,"text":"The Program Status Protocol","id":"the-program-status-protocol"},{"level":2,"text":"Implement It","id":"implement-it"}]}}