--- title: A Terminal Protocol for Program Status (OSC 7501) description: A new terminal escape sequence specification, OSC 7501 (the Program Status Protocol), lets any program report its status directly to the terminal: idle,... canonical: https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: A Terminal Protocol for Program Status (OSC 7501) | daily.dev og:description: A new terminal escape sequence specification, OSC 7501 (the Program Status Protocol), lets any program report its status directly to the terminal: idle,... og:url: https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p og:image: https://api.daily.dev/og/posts/9LzZbsx6p.png og:image:alt: A Terminal Protocol for Program Status (OSC 7501) og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # A Terminal Protocol for Program Status (OSC 7501) **[Mitchell Hashimoto](https://daily.dev/sources/mitchellh)** · 7 min read · 1 upvotes · 0 comments ## Summary A new terminal escape sequence specification, OSC 7501 (the Program Status Protocol), lets any program report its status directly to the terminal: idle, working, waiting on the user, finished, or failed, along with a reason. The author, who maintains the Ghostty terminal emulator and works on Superlogical, created the spec to replace fragile heuristics (like Herdr's regex-based title detection) and non-terminal APIs used by agentic inbox tools (Herdr, cmux, Agent Deck) that track multiple running coding agents. The protocol uses simple key=value pairs sent over the pty, works over SSH and containers, supports hierarchical task trees, and has already been prototyped in Terraform, Claude Code, Codex, Homebrew, libghostty, and Rex with implementations as short as a dozen lines. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### What is OSC 7501 and what problem does it solve? OSC 7501 is the Program Status Protocol, a terminal escape sequence specification allowing any program to report its state (idle, working, done, blocked, or error) directly through the pty. It replaces fragile heuristics like reading window titles for spinner characters and inbox-specific socket APIs, working uniformly over SSH and containers since it uses the pty every program already has. _Developers building terminal tools or agent orchestration can track new specs like this one through daily.dev._ ### How do agentic inbox tools like Herdr currently detect whether a coding agent is working or blocked? Herdr uses detection manifests, which are TOML rule files matching patterns like Braille spinner characters or half-circle busy spinners in the window title to classify Claude Code as idle, working, or blocked. These rules are fragile; the Claude Code manifest alone had ten changes in three months as the agent's UI changed, such as switching spinner characters after version 2.1.228. _Anyone orchestrating multiple coding agents can follow protocol changes like this via daily.dev._ ### How do you format an OSC 7501 status message in a shell script? Send an escape sequence of the form ESC ] 7501 ; state=working:msg= ESC \, using printf and base64 encoding for the message. A working shell function wraps this in a `status()` call, for example reporting 'working', then 'done' or 'error' after a command like rsync finishes or fails, requiring no SDK, sockets, or JSON. _Developers scripting terminal status reporting can keep up with protocols like this through daily.dev._ ## Similar posts on daily.dev - [Hyperlinks in Terminal Emulators](https://daily.dev/posts/hyperlinks-in-terminal-emulators-5awqdouux) · Hacker News · 1 upvotes · 0 comments - [Ghostty Terminal: Never Understood the Hype Until I tried it](https://daily.dev/posts/ghostty-terminal-never-understood-the-hype-until-i-tried-it-fhwfcvjbc) · It's Foss · 54 upvotes · 5 comments - [How Terminals Work](https://daily.dev/posts/how-terminals-work-41sp4ewvn) · Lobsters · 1 upvotes · 0 comments --- Tags: [#ai-agents](https://daily.dev/tags/ai-agents), [#claude-code](https://daily.dev/tags/claude-code) [View this post on daily.dev](https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"A Terminal Protocol for Program Status (OSC 7501)","url":"https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p"},"datePublished":"2026-10-06T20:55:24.021Z","dateModified":"2026-10-06T21:01:48.464Z","description":"A new terminal escape sequence specification, OSC 7501 (the Program Status Protocol), lets any program report its status directly to the terminal: idle,...","image":"https://media.daily.dev/image/upload/s--P4t4XyoV--/f_auto/v1722860399/public/Placeholder%2001","thumbnailUrl":"https://media.daily.dev/image/upload/s--P4t4XyoV--/f_auto/v1722860399/public/Placeholder%2001","isAccessibleForFree":true,"articleSection":"Mitchell Hashimoto","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Mitchell Hashimoto","logo":"https://media.daily.dev/image/upload/s--9zTxbLer--/f_auto/v1735476334/logos/mitchellh","url":"https://daily.dev/sources/mitchellh"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"ai-agents,claude-code","timeRequired":"PT7M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Mitchell Hashimoto","item":"https://daily.dev/sources/mitchellh"},{"@type":"ListItem","position":3,"name":"A Terminal Protocol for Program Status (OSC 7501)"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/a-terminal-protocol-for-program-status-osc-7501--9lzzbsx6p#faq","mainEntity":[{"@type":"Question","name":"What is OSC 7501 and what problem does it solve?","acceptedAnswer":{"@type":"Answer","text":"OSC 7501 is the Program Status Protocol, a terminal escape sequence specification allowing any program to report its state (idle, working, done, blocked, or error) directly through the pty. It replaces fragile heuristics like reading window titles for spinner characters and inbox-specific socket APIs, working uniformly over SSH and containers since it uses the pty every program already has. Developers building terminal tools or agent orchestration can track new specs like this one through daily.dev."}},{"@type":"Question","name":"How do agentic inbox tools like Herdr currently detect whether a coding agent is working or blocked?","acceptedAnswer":{"@type":"Answer","text":"Herdr uses detection manifests, which are TOML rule files matching patterns like Braille spinner characters or half-circle busy spinners in the window title to classify Claude Code as idle, working, or blocked. These rules are fragile; the Claude Code manifest alone had ten changes in three months as the agent's UI changed, such as switching spinner characters after version 2.1.228. Anyone orchestrating multiple coding agents can follow protocol changes like this via daily.dev."}},{"@type":"Question","name":"How do you format an OSC 7501 status message in a shell script?","acceptedAnswer":{"@type":"Answer","text":"Send an escape sequence of the form ESC ] 7501 ; state=working:msg= ESC \\, using printf and base64 encoding for the message. A working shell function wraps this in a `status()` call, for example reporting 'working', then 'done' or 'error' after a command like rsync finishes or fails, requiring no SDK, sockets, or JSON. Developers scripting terminal status reporting can keep up with protocols like this through daily.dev."}}]} ```