; <body> BEL` | | `OSC 99` | kitty | `ESC ] 99 ; <metadata> ; <payload> ST` | For `OSC 99`, Clusto reads the title and body payloads, joins chunks sent with `d=0`, and decodes payloads marked `e=1` (base64). Example from a shell script: ```bash printf '\e]777;notify;Build;Done\a' ``` Limits and defaults: * The title defaults to the session name when the sequence has none. * At most one notification per second per session. Extra ones are dropped. * The body is capped at 2048 characters and the title at 192. * Control characters are stripped from both. ## Progress bar The ConEmu and Windows Terminal progress sequence shows a thin bar at the bottom of the session row in the sidebar: ```bash printf '\e]9;4;1;40\a' # normal, 40 percent printf '\e]9;4;0\a' # remove ``` Format: `ESC ] 9 ; 4 ; <state> ; <percent> BEL`. | State | Meaning | | --- | --- | | `0` | Remove the bar | | `1` | Normal, with a percent | | `2` | Error | | `3` | Indeterminate | | `4` | Paused | The bar clears on its own after 15 seconds without an update, so a program that exits without sending `0` does not leave a stuck bar. Updates are pushed to clients at most every 500 ms. ## Program Status Protocol (OSC 7501) OSC 7501 is the Program Status Protocol from Superlogical (Rex). It is a structured way for a tool to report whether it is idle, working or blocked. See the [Rex documentation](https://www.superlogical.com/rex/docs) for the spec. ```text ESC ] 7501 ; state=<state>[:kind=<kind>][:progress=N][:app=<name>][:title=<b64>][:msg=<b64>] ST ``` States: `idle`, `working`, `done`, `blocked`, `error`, `clear`. Kinds (for `blocked`): `permission`, `question`, `auth`. `title` and `msg` are base64. How Clusto maps the states: | State | Result | | --- | --- | | `working` | The session spinner turns on | | `blocked` | The `?` [waiting marker](/agent-attention) with the kind as the reason and `msg` as the copyable prompt | | `done` | A "name finished" notification with `msg` as the body | | `error` | A "name failed" notification | | `idle`, `clear` | Clears the working and waiting state | Notes: * Only the root record is used. Reports that carry an `id` are accepted but not shown yet. * Once a session sends any OSC 7501 report, Clusto stops using its own heuristics for that session (title spinner, Copilot footer) and ignores `OSC 9;4` progress. This lasts until a full terminal reset (`ESC c`). * Clusto answers the feature query `ESC ] 7501 ; ? ESC \` with `ESC ] 7501;?:states=idle,working,done,blocked,error:kinds=permission,question,auth ESC \`, so a tool can detect support before sending reports. Because the sequences travel in the terminal stream, this works for any program on any node, including over SSH sessions, without the `clusto` CLI on the remote machine. ## Terminal bell A BEL character in a terminal you are not focused on shows a bell-ring icon on that session's row in the sidebar. The icon stays until you focus the session. On desktop, Clusto also flashes the taskbar entry when the app is in the background. This happens at most once every 5 seconds and never for a muted session. ## True color With the `terminal.truecolor` release flag on, new sessions start with `COLORTERM=truecolor` so tools render 24-bit color. If the session environment already sets `COLORTERM`, your value wins. The flag is off by default while it is checked against a Windows report of agent TUIs freezing. Turn it on for the cluster in **Settings > Labs**, or for one node with `[features] "terminal.truecolor" = true` (see [Feature Flags](/feature-flags)). ## Related * [Agent Waiting Marker](/agent-attention) - the `?` marker and the CLI contract * [Background Notifications](/background-notifications) - alerts when the app is closed * [Terminal Workspace](/terminal-workspace)

--- url: https://clusto.app/docs/terminal-notifications.md description: >- Programs in a terminal can raise Clusto notifications, report progress, and signal state through standard escape sequences (OSC 9, OSC 777, OSC 99, OSC 9;4, OSC 7501), plus the terminal bell indicator. --- # Terminal Notifications, Progress and Bell Programs running in a Clusto terminal session can talk to Clusto directly with standard terminal escape sequences. No CLI, hook or setup is needed: print the sequence and Clusto reacts. This is free on every plan. The daemon parses the sequences on the node that owns the session. They work with no client attached, and they reach the same notification path as agent-finished alerts: the native popup, the sound, the [mobile background poller](/background-notifications) and the per-session mute. ## Desktop notifications Three common sequences raise a notification: | Sequence | Origin | Form | | --- | --- | --- | | `OSC 9` | iTerm2 | `ESC ] 9 ; BEL` | | `OSC 777` | rxvt, Ghostty | `ESC ] 777 ; notify ; ; <body> BEL` | | `OSC 99` | kitty | `ESC ] 99 ; <metadata> ; <payload> ST` | For `OSC 99`, Clusto reads the title and body payloads, joins chunks sent with `d=0`, and decodes payloads marked `e=1` (base64). Example from a shell script: ```bash printf '\e]777;notify;Build;Done\a' ``` Limits and defaults: * The title defaults to the session name when the sequence has none. * At most one notification per second per session. Extra ones are dropped. * The body is capped at 2048 characters and the title at 192. * Control characters are stripped from both. ## Progress bar The ConEmu and Windows Terminal progress sequence shows a thin bar at the bottom of the session row in the sidebar: ```bash printf '\e]9;4;1;40\a' # normal, 40 percent printf '\e]9;4;0\a' # remove ``` Format: `ESC ] 9 ; 4 ; <state> ; <percent> BEL`. | State | Meaning | | --- | --- | | `0` | Remove the bar | | `1` | Normal, with a percent | | `2` | Error | | `3` | Indeterminate | | `4` | Paused | The bar clears on its own after 15 seconds without an update, so a program that exits without sending `0` does not leave a stuck bar. Updates are pushed to clients at most every 500 ms. ## Program Status Protocol (OSC 7501) OSC 7501 is the Program Status Protocol from Superlogical (Rex). It is a structured way for a tool to report whether it is idle, working or blocked. See the [Rex documentation](https://www.superlogical.com/rex/docs) for the spec. ```text ESC ] 7501 ; state=<state>[:kind=<kind>][:progress=N][:app=<name>][:title=<b64>][:msg=<b64>] ST ``` States: `idle`, `working`, `done`, `blocked`, `error`, `clear`. Kinds (for `blocked`): `permission`, `question`, `auth`. `title` and `msg` are base64. How Clusto maps the states: | State | Result | | --- | --- | | `working` | The session spinner turns on | | `blocked` | The `?` [waiting marker](/agent-attention) with the kind as the reason and `msg` as the copyable prompt | | `done` | A "name finished" notification with `msg` as the body | | `error` | A "name failed" notification | | `idle`, `clear` | Clears the working and waiting state | Notes: * Only the root record is used. Reports that carry an `id` are accepted but not shown yet. * Once a session sends any OSC 7501 report, Clusto stops using its own heuristics for that session (title spinner, Copilot footer) and ignores `OSC 9;4` progress. This lasts until a full terminal reset (`ESC c`). * Clusto answers the feature query `ESC ] 7501 ; ? ESC \` with `ESC ] 7501;?:states=idle,working,done,blocked,error:kinds=permission,question,auth ESC \`, so a tool can detect support before sending reports. Because the sequences travel in the terminal stream, this works for any program on any node, including over SSH sessions, without the `clusto` CLI on the remote machine. ## Terminal bell A BEL character in a terminal you are not focused on shows a bell-ring icon on that session's row in the sidebar. The icon stays until you focus the session. On desktop, Clusto also flashes the taskbar entry when the app is in the background. This happens at most once every 5 seconds and never for a muted session. ## True color With the `terminal.truecolor` release flag on, new sessions start with `COLORTERM=truecolor` so tools render 24-bit color. If the session environment already sets `COLORTERM`, your value wins. The flag is off by default while it is checked against a Windows report of agent TUIs freezing. Turn it on for the cluster in **Settings > Labs**, or for one node with `[features] "terminal.truecolor" = true` (see [Feature Flags](/feature-flags)). ## Related * [Agent Waiting Marker](/agent-attention) - the `?` marker and the CLI contract * [Background Notifications](/background-notifications) - alerts when the app is closed * [Terminal Workspace](/terminal-workspace)