ysskrishna logoysskrishna
Cover image for OSC 7501 in Python: Tell the Terminal When Your CLI Is Working, Blocked or Done

OSC 7501 in Python: Tell the Terminal When Your CLI Is Working, Blocked or Done

ysskrishna profile photoysskrishna
3 min read
Python
Python CLI
DevOps & Infrastructure

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 osc7501

It 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=True to force it.
  • clear() with no id removes every record the terminal holds.

The states and reasons

StateMeaning
idleNothing running
workingBusy, optionally with a progress value and a message
blockedWaiting on the user. Give a kind: permission, question or auth
doneFinished
errorFailed
clearRemove 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(...) writes working as soon as you call it, before the with block.
  • A clean exit writes done with no message, unless you already called job.done() or job.error().
  • An exception writes error.
  • Ctrl+C (KeyboardInterrupt) writes idle.

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

  1. pip install osc7501.
  2. Add one blocked(...) call right before your CLI's first prompt.
  3. Wrap your longest command in with working(...) as job: and try it in a terminal from the support matrix.

Further reading

Continue exploring

ProductPyPIOSC 7501

OSC 7501

Tell your terminal when your CLI is working, blocked, finished, or failed.
DevOps & Infrastructure
PyPI Packages
Python
Python CLI
BlogCover image for caffeinate for Windows: Keep a Locked-Down Laptop Awake Without Installing Anything

caffeinate for Windows: Keep a Locked-Down Laptop Awake Without Installing Anything

DevOps & Infrastructure
PowerShell
4 min read
ProductPyPIDocker Detector

Docker Detector

One call tells your Python app whether it is running inside Docker.
DevOps & Infrastructure
PyPI Packages
Python
uv
ProductPyPIContainer Detect

Container Detect

One Python call to learn if your process is inside Docker, Podman, Kubernetes, or another Linux container.
DevOps & Infrastructure
PyPI Packages
Python
uv
ProductGitHub MarketplaceRelease from Changelog or Tag

Release from Changelog or Tag

The changelog section you already wrote becomes the GitHub Release.
DevOps & Infrastructure
GitHub Marketplace Actions
GitHub Actions
Bash
ProductNextjs Multi-Stage Docker

Nextjs Multi-Stage Docker

See the real size gap between one-stage and multi-stage Next.js Docker builds.
DevOps & Infrastructure
Starter Kits & Boilerplates
Docker
Next.js