Clusto Docs

Appearance

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 and the per-session mute.

Desktop notifications ​

Three common sequences raise a notification:

SequenceOriginForm
OSC 9iTerm2ESC ] 9 ; <body> BEL
OSC 777rxvt, GhosttyESC ] 777 ; notify ; <title> ; <body> BEL
OSC 99kittyESC ] 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.

StateMeaning
0Remove the bar
1Normal, with a percent
2Error
3Indeterminate
4Paused

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 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:

StateResult
workingThe session spinner turns on
blockedThe ? waiting marker with the kind as the reason and msg as the copyable prompt
doneA "name finished" notification with msg as the body
errorA "name failed" notification
idle, clearClears 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).

Clusto - remote AI coding agents over WebSocket.

clusto.app