OSC 7501: your coding agent can now tell your terminal it needs you

Run three coding agents in three terminal tabs, and starting them is the easy part. The hard part is knowing which one has stopped and is waiting for you. Until October, every agent had its own answer: a bell, a notification hook, a changed tab title. Now there’s a shared one.
What OSC 7501 is
OSC 7501 is the Program Status Protocol, a proposal by Mitchell Hashimoto (revision 0.4, October 10, 2026). It “lets a program tell its terminal what state it is in”: at rest, working, waiting on you, finished or failed, and why.
A program reports its state with an escape sequence, the same family as the one that sets a window title:
OSC 7501 ; state=working:app=make:msg=QnVpbGRpbmcgZG9jcw== STstateisidle,working,blocked,doneorerror, orclearto remove it.kindsays what ablockedprogram needs:permission,questionorauth.progressis 0 to 100, withworkingorblocked.appis a stable program name, likecargo.msgandtitleare base64 of UTF-8 text: a line on what it’s doing or waiting for, and a short label.
A few rules make it hold up in practice:
- Each report replaces the last one whole.
workingandblockeddisappear when the process exits or the next shell prompt appears, so a crashed program doesn’t leave a stale “working” behind.doneanderrorstay until you’ve seen them.- Everything in a report is untrusted: the terminal refuses control characters in the text, and never sends titles or messages back to the program.
- How it looks is the terminal’s choice. The spec says a terminal may notify you when a status changes, and should rate-limit any notification or sound.
Which agents send it
From each project’s release notes, and the community tracker Are we OSC 7501 yet? (updated November 4):
| Agent | Sends OSC 7501 | Since |
|---|---|---|
| Claude Code | Yes | 2.1.295, October 8 |
| Codex | Yes | rust-v0.163.0, October 15 |
| Grok Build | Yes | 1.0.52, October 11 |
| OpenCode | OpenCode 2 only | 2.2.0, October 27 |
| Gemini CLI | Not yet | an open issue asks for it; a pull request closed unmerged on November 8 |
Claude Code’s changelog puts it plainly: “terminals that implement it can show whether Claude Code is working, waiting on you, or done.”
Which terminals show it
That’s the other half, and it’s earlier. Per the tracker and kitty’s changelog:
- Shipped: iTerm2 3.7.5 (October 15), kitty 0.50.0 (November 3), and a few smaller terminals.
- Not yet: Ghostty (its library parses the reports, but the app drops them), WezTerm, Windows Terminal, Alacritty, VS Code’s terminal and Warp.
Some apps built around terminals read it too. Herdr, for one, lists an agent only once it reports a status this way.
So on iTerm2 3.7.5 or kitty 0.50.0 or later, with a recent Claude Code or Codex, the status can already show. Elsewhere, the agent sends it and the terminal ignores it, which is harmless.
Send it from your own scripts
Nothing about it is specific to agents. A long build, a test run or a deploy script can report the same way. In bash or zsh:
# osc_status <state> [message]osc_status() { local msg="" [ -n "$2" ] && msg=":msg=$(printf '%s' "$2" | base64 | tr -d '\n')" printf '\033]7501;state=%s:app=deploy%s\033\\' "$1" "$msg"}
osc_status working "Deploying to staging"if ./deploy.sh staging; then osc_status done "Staging is up"else osc_status error "Deploy failed"fi\033] opens the sequence and \033\ ends it. Two more from the spec:
- Waiting for input? Say why with a
kind, so a terminal can tell a question from a password prompt:printf '\033]7501;state=blocked:kind=question:app=deploy\033\\'. - Done with it?
printf '\033]7501;state=clear\033\\'removes every status the program set.
A few things to know
- Multiplexers: the report has to get through them, and the spec doesn’t cover tmux. Herdr’s FAQ notes that agents inside tmux within Herdr can’t report their status.
- No report, no status: a program that doesn’t send one shows nothing, which today includes Gemini CLI.
- It’s a proposal: revision 0.4, so details can still change.
Doing this in Moontors
I build Moontors, a free desktop app that runs Claude Code, Codex, Gemini CLI, Grok Build and OpenCode side by side, so take this part as the maker’s view.
Moontors gets each session’s status from the agent’s own protocol rather than from the terminal, so it knows what a session is waiting on, not only that it’s waiting, Gemini CLI’s sessions included:
- One count in the header for every session waiting on you, for an answer to a question, a plan to approve or a permission. Click it to go to the next one. (The header)
- Each card shows why. A waiting session’s card shows the question or plan it’s asking. (Questions and plans)
- Done stays blue until you’ve looked. (Done and notifications)
- Notifications on your computer when a session starts waiting for you, hits an error or finishes. Away from your desk, the phone app’s board shows the same waiting and done counts, and you answer from there.
Whatever you run your agents in, OSC 7501 is worth knowing: it turns “which tab was that?” into something your terminal can answer.
AI did the writing, I did the reading, and we both took credit.