A Terminal Protocol for Program Status (OSC 7501)
mitchellh.com
mitchellh.com
Starting an emacs window in the fg:
% emacs ^T load: 0.32 cmd: emacs-31.1 64938 [select] 2.89r 0.75u 0.06s 6% 122404k
This way, anyone who needs AI agent status can just send SIGINFO signal and wait for the response.
^T is a Pull
OSC7591 is a Push
As long as the signal is built, like any good interrupt code, to only do message passing instead of blocking work then there won’t be any performance issues. We’re polling between a handful of local processes that are in the order of human-computer interaction, not polling remotely in a large scale way.
It's already implemented by `systemd` and is available in Ubuntu 26.04.
I'd rather see `OSC 3008` being extended.
https://x.com/mitchellh/status/2108316851537322111?__frodo=r...
Alternative version:
https://nitter.click/mitchellh/status/2108316851537322111?__...
Something that reads 'ASCII byte range > 0x7f' in the second paragraph of its syntax description has not started well. ASCII has no codes above DEL, and allowing the C1 controls is useless and actually leads to problems of command sequences and control sequences inside command strings, since CSI, SOS, and the like are C1 controls.
The total lack of mention of the terminal bell in the article is weird. I think it needs to be addressed for the protocol to be taken seriously. More granular info sounds nice, but also nice is the simplicity of the bell.
https://www.superlogical.com/rex/docs/build/program-status#r...
Also - definitely a mention of the terminal bell on https://www.superlogical.com/rex/docs/automate/shell-scripti...
rex events -s work --json |
jq -r 'select(.payload.event.payload.name == "bell")
| .payload.event.payload.block_id'My iTerm2 is configured to show activity, new-output and visual bell in the tab. On Linux I have an approximation for WezTerm.
I have a bell command that I can use in a pipeline or sequence to produce the bell on events I'm interested in. Trivial case is when a program finishes.
I have a fancy alias that can be used in a shell command sequence and which produces different sounds depending on the exit status of the preceding command in addition to sending the terminal bell.
Totally going to extend this for myself with a custom key that encodes a reverse route on each hop so I can easily jump to the window/tab/pane that emitted it, or send back custom actions into a given pane like a permission approve/deny.
This OSC 7501 pushes state from Program to Terminal; with an explicit running/idle/fubar "state" field but also K/V data. Then Terminal can provide interactions thereof, such as display it.
What I want is for the Program to push the terminal some map of "key:command" which is available for the terminal to provide interactions thereof. Maybe that can come through just as a key in this?
Here's the motivation: when using a TUI on a phone or tablet, the keyboarding experience is horrible (unless you have a physical keyboard). It takes up too much real estate and most of the time there's only three keys action you want to hit.
An obvious solution is to put up HTML buttons and other chrome for users to tap. Personally, I've handled that bespoke at the library+application level, where the Golang and HTML+JS container work together. There's some reusability because it can just take a BubbleTea Help Model (holds keybindings), but it is limited.
In the last few weeks, I've started seeing Claude do this unasked for me (creating parallel Web/TUI interfaces), but it was actually building more complicated Web scaffolding, rather than it being deterministically rendered from a specification by the harness.
Here's demo of it enabled in booba, which is our Golang TUI remoting tool: https://nimblemarkets.github.io/go-booba/demos/actions/
The browser UX comes as a JSON spec over OSC 7501, that spec generated from the BubbleTea Help model.
[1] an overhaul of the original which uses libghostty-vt bindings instead of a patchset, fixes Bidi fonts, and adds WebGPU/WebGL renderer, but really a placeholder for whatever Ghostty/Superlogical cooks up.
That's what I thought in the beginning. Once I read the spec to the end, it's clear to me that it's overly specific to one use-case — TUI AI agents.
E.g. `kind := permission | question | auth` doesn't make much sense anywhere outside of that use case. The list goes on...
I also found comms around it super muddy, AI agent use case is mentioned but deceivingly watered down with other use-cases.
Overall, that spec is no where close to Kitty/Kovid's level. It's super sad, since mitchellh's work is usually super high quality.
I hope the community will push back and the spec will get better.
There’s always two people at every company who refuse to set up auth automation though, so you end up handling it. They are very stubborn. Even when it trips them up in front of observers while executing an urgent task, I’ve only occasionally convinced them to agree to set up trust instead of typing a password every single time.
Which is to say, I have to support password prompts even though they drive me up the wall.
CLI can also _blank_, do we want to support it as well?
I actually created a separate golang library with something like this in mind: https://github.com/danudey/ansipants
The original idea I had being that CI environments, or anywhere that shows terminal output, could use a streaming ANSI parsing library to detect when a program sent a 'change window title' OSC event and then start a new collapsable section in its output. This would let programs update the actual terminal window title with its current state when running locally and update the CI interface when running in CI.
Adding in the ability to specify the program's current status and (optionally) progress could be extremely useful in CI environments as well. Imagine, for example, a long-running analysis task which uses OSC 7501 to say that it's currently running and is 75% of the way done. CI could expose that in the UI to provide useful information to the end-user without having to print a progress bar or multiple progress lines to the fake terminal it's being run in.
The thing is when you expect a task to take five minutes, you don’t watch it, you find something else you expect to take five minutes and do that instead. When that ends up taking ten minutes, or when you remember what you were doing before you started, you finally come back around ten minutes later to find that either the task completed four minutes ago, or it failed after ten seconds and you’ve wasted ten now.
The audio was the best out of band notification I had at my disposal 20 years ago.
My first thought when reading this was actually terminal multiplexing however, like screen or tmux. But I’m also always doing the terminal dance because I work on 4 FOSS projects and I keep 1+ terminal open per project so I can jump in and do bug fixes or pull PRs I’ve landed.
I've also never really fully understood why terminfo seems to be a singular package, and not something like man pages where, e.g., each terminal drops in their respectively entry.
https://vt100.net/emu/dec_ansi_parser
Just look how many paths lead to the "csi ignore" state.
Do you have a specific physical terminal that's even older than the VT100 that you're worried about?
And it isn't just real terminals. Several terminal emulators are bad at handling syntactically valid but unknown to the emulator control strings. There are several whose authors hadn't read ECMA-35 and ECMA-48, and based their programs on samizdat lists of control sequences circulating years ago, without realizing that there was a full consistent syntax underlying them. Unrecognized control sequences are sometimes just printed as text, or worse.
Indeed, OSC itself is notorious for being such a case, where for a time some emulators expected BEL instead of ST as the string terminator.
> Correctness – if you were to feed this parser a stream of characters that is random or deliberately pathological, it is claimed that this parser will exhibit the same visible behaviour as any one of DEC’s 8-bit ANSI-compatible terminals, from VT220 to VT525. A VT100-series parser would be simpler still, as the VT100 only supports 7-bit characters.
To your other point, if we're not talking about replacing expensive hardware anymore, but just obscure buggy software--shouldn't they fix the bugs instead of the entire industry halting all forward progress for the rest of time?
We've done this before. Hyperlinks are a pretty recent introduction, and are widespread by now. So either these buggy terminal emulators were already fixed as hyperlink usage became widespread, or they're unmaintained and already broken by hyperlinks. Either way, new standards won't make the situation any worse.
terminfo's problem is that it is really difficult to make changes that extend or do not fit the original paradigm, not least because the actual database format does things like have a fixed set of implicitly-named boolean capabilities, with any additional capabilities having to be named 'extensions'.
* https://github.com/mauke/unibilium/blob/master/secret/termin...
But other problems include terminfo's model of how things work, such as function keys for example, not really matching how they actually work in terminals and terminal emulators. For function keys, for example, DEC terminals allowed modifier state to be sent in parameters to DECFNK. terminfo's design had no concept of this.
Nushell already kind of has this philosophy - there is a separation between the actually scripting of tools (prints out structured json), and the visualization back to the user if it's a terminal. On top of this, you could say, have some awareness of, "If I know I'm the remote, I can pass a json list to the userdirectly and have them render client-side, rather than pretend to be a terminal".
It may be inefficient for some cases, but then you could actually say, execute the vision of mosh.
The terminal, in the abstract, is one of the best abstractions ever. The implementation is tied down to 1980s tech.
You could always spin up a "normal" terminal if you're ssh'd into some remote server to do sysadmin stuff. IMO you shouldn't be installing personal configs on there anyways (maybe allow a copy pasted .bashrc and .tmux.conf)
Another thing you could do - neovim already has neovide, you could make this native, right? You would maybe write an adapter for neovim on the remote (again, all of this is in vresion control + nix; this is how I use dotfiles; and at work I'm doing nothing fancy since I don't have control over host, it's just temrinal integration) - if I type "nvim" in the "shell" application, it actually opens up its msgpack GUI protocol.
Maybe at some point you're just re-inventing emacs though.
For example, dd or rsync would be quite simple to enable with this.
APC is far less supported overall by terminals (for example, Terminal.app on macOS would simply dump APC to the screen, ignore the framing, and treat the APC data as normal pty data, and Terminal.app is used by a LOT of people). Plus, its anything-goes format makes it hard to ship safe protocols that overlap with others (APC was always meant afaik for _one_ protocol -- the application's, not multiplexing many).
Compare this to OSC which is well supported, has a well defined multiplexing format (the first number), and has a well defined framing that all terminals I know of ignore for unknown values. That's perfect.
As the Arcan project so eloquently stated[1]: "Terminal emulators emulate a machine that has never existed, a fantasy computer." More details in the link by people I respect who have worked on this problem far longer than I have.
[1]: https://arcan-fe.com/2025/01/27/sunsetting-cursed-terminal-e...
In fact, you can say the exact same thing about OSC (it was meant for one protocol, the operating system's) as you just did about APC. Because that's what ECMA-48 actually says: 'The interpretation of the command string depends on the relevant operating system.'
There is no operating system standard for this in the Unices or in Linux-based operating systems. As I said, this is something that haphazardly grew in the last decade or so as people decided that they needed some kind of terminal control string, and how dtterm and xterm had been processing OSC (very limited compared to all of the things that people have nowadays tacked on) was there.
- detect animation in the terminal (defined as changes without user input)
- when the animation stops it needs attention
- if it doesn't have the user's attention, ring some sort of bell
I built such a terminal specifically because this problem was driving me nuts. The marketing for it isn't finished yet (planning to launch next week) but it's been my daily-driver for months if you want to try it out: https://dormouse.sh/
But OSC 7501 seems like a great idea, I'll track its implementation here: https://github.com/diffplug/dormouse/issues/1079
Super brittle.