OSC 7501

Report terminal program status with OSC 7501.

Features

• States: idle, working, done, blocked, error, and clear
• One job: a context manager that repeats app, id, and title and closes the job for you
• Safe text: control characters become spaces before base64, so one newline cannot drop the report
• Optional probe: ask the terminal whether it supports OSC 7501
• Zero dependencies: the library only uses the Python standard library
• TTY gate: reports are skipped when stderr is a pipe, unless you pass enabled=True

Why OSC 7501?

OSC 9;4 progress can say that a program is busy, at a percentage, or failed. It has no message and no way to say the program is waiting on the user. A window title is one free-form string.

OSC 7501 adds a state, a reason (permission, question, or auth), and a stable app name. The terminal decides how to show that. A terminal that does not know the sequence ignores it, so sending a report is safe.

Spec: Program Status Protocol, revision 0.4 (2026-10-10).

Installation

pip install osc7501

Usage Examples

Helpers

from osc7501 import blocked, done, working

working(progress=40, msg="Building docs")
blocked(kind="permission", msg="Approve deploy?")
done(msg="Docs built")

Each report replaces the terminal's record. Repeat every field you still want. clear() with no id removes every record in the terminal.

Reports go to stderr, and only when it is a terminal.

One job

from osc7501 import working

with working(app="make", msg="Building docs") as job:
    job.blocked(kind="question", msg="Overwrite config.toml?")
    job.done(msg="Docs built")

working() writes working when you call it, before the with block. Enter writes nothing more. A clean exit writes done with no message. An exception writes error. KeyboardInterrupt writes idle. If you already called job.done() or job.error(), the exit writes nothing.

msg for kind="auth" is the prompt, never the secret.

Detection

from osc7501 import detect

print(detect().result)

Call detect() before reading input. It can consume keystrokes typed during the wait. On Windows, or when /dev/tty cannot be opened, the result is Detection.UNKNOWN. Helpers never probe on their own.

Where reports show up

Which terminals show a report is tracked in the awesome-osc7501 matrix. This library does not wrap reports for tmux.

API Reference

Learn More

• Program Status Protocol (OSC 7501)
• Mitchell Hashimoto: A Terminal Protocol for Program Status
• awesome-osc7501

Acknowledgments

• Mitchell Hashimoto, for the specification
• Jonah Snider, for osc-status
• Adam Duke, for pst

Built and maintained by

osc7501 is built and maintained by:

	Name	GitHub	Role
	Y. Siva Sai Krishna	@ysskrishna	Creator

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

If you find this library helpful:

• ⭐ Star the repository
• 🐛 Report issues
• 🔀 Submit pull requests
• 💝 Sponsor on GitHub

License

MIT © Y. Siva Sai Krishna - see LICENSE file for details.

Author's GitHub • Author's LinkedIn • Report Issues • Package on PyPI