You start a long task in one terminal tab and switch to another. Ten minutes later you come back and find it has been sitting on Overwrite config.toml? [y/N] for nine of them.
A progress bar would not have helped. It says "busy", not "waiting for you".
OSC 7501 fixes that. It is a terminal escape sequence that lets a program report its state (working, blocked, done or error), why it is blocked, and which app is reporting. The terminal decides how to show it: a badge, a tab colour, a notification. A terminal that does not know the sequence ignores it.
I wrote a small Python library for it: osc7501. This post shows how to use it.
Install
pip install osc7501It needs Python 3.11+ and has zero dependencies: only the standard library.
Your first report
from osc7501 import blocked, done, working
working(progress=40, msg="Building docs")
blocked(kind="permission", msg="Approve deploy?")
done(msg="Docs built")Three things to know:
- Each report replaces the last one. Repeat every field you still want shown.
- Reports go to stderr, and only when stderr is a terminal. If you pipe output to a file, nothing is written, so logs stay clean. Pass
enabled=Trueto force it. clear()with noidremoves every record the terminal holds.
The states and reasons
| State | Meaning |
|---|---|
idle | Nothing running |
working | Busy, optionally with a progress value and a message |
blocked | Waiting on the user. Give a kind: permission, question or auth |
done | Finished |
error | Failed |
clear | Remove the record |
For kind="auth", msg is the prompt ("Enter your token"), never the secret itself.
Wrap a whole job
For anything with more than one step, use the context manager. It repeats app, id and title for you and closes the job:
from osc7501 import working
with working(app="make", msg="Building docs") as job:
build_pages()
job.update(progress=60, msg="Rendering diagrams")
if config_exists():
job.blocked(kind="question", msg="Overwrite config.toml?")
ask_user()
job.done(msg="Docs built")What it writes, and when:
working(...)writesworkingas soon as you call it, before thewithblock.- A clean exit writes
donewith no message, unless you already calledjob.done()orjob.error(). - An exception writes
error. Ctrl+C(KeyboardInterrupt) writesidle.
job.update() skips a byte-identical repeat, so you can call it in a loop without flooding the terminal.
Ask the terminal if it supports OSC 7501
Usually you do not need to: unsupported terminals ignore the sequence. If you want to know:
from osc7501 import detect
print(detect().result)Call detect() before reading input, because it can consume keystrokes typed during the wait. On Windows, or when /dev/tty cannot be opened, the result is Detection.UNKNOWN. The helpers never probe on their own.
Messages are sanitized
Control characters in your message become spaces before encoding, so a stray newline cannot break the report. You can pass user-supplied text without hand-escaping it.
Where reports show up
Support varies by terminal. The community awesome-osc7501 matrix tracks which terminals show reports. The library does not wrap reports for tmux.
Build a sequence without writing it
If you want the raw string, for a test or for another output stream:
from osc7501 import encode
seq = encode("blocked", kind="question", msg="Continue?", app="mytool")encode() builds one sequence and does not write anything.
What to do next
pip install osc7501.- Add one
blocked(...)call right before your CLI's first prompt. - Wrap your longest command in
with working(...) as job:and try it in a terminal from the support matrix.







