Reference
Show status from your scripts
Copy-paste lines that put a status mark on a terminal tab, list it in Needs you and notify you.
Make a script in a terminal tab show Working, Done, Needs your OK or Failed, as agent chats do, by printing one line.
When the script needs you, fails or finishes, chaar lists it in Needs you and notifies you. Agent chats report their status on their own. An agent you start yourself in a terminal tab shows marks only if it prints these lines: see Work with AI agents.
Try it
Run this in a terminal tab, then switch to another tab within 10 seconds:
$ printf '\033]7501;state=working\a'; sleep 10; printf '\033]7501;state=done\a'The tab shows Working, then Done, and you get a notification.
In a script, report as you go:
printf '\033]7501;state=working\a'
if make test; then
printf '\033]7501;state=done\a'
else
printf '\033]7501;state=error\a'
fiThe machine reads these lines, not your device, so the status keeps updating while no app is open.
The line for each status
Copy the line for the status you want.
Working
$ printf '\033]7501;state=working\a'Working, 40%
$ printf '\033]7501;state=working:progress=40\a'Needs your OK
$ printf '\033]7501;state=blocked:kind=permission\a'Needs your answer
$ printf '\033]7501;state=blocked:kind=question\a'Needs your sign-in
$ printf '\033]7501;state=blocked:kind=auth\a' Needs you, without saying what for (◆ in the chaar command)
$ printf '\033]7501;state=blocked\a'Done
$ printf '\033]7501;state=done\a'Failed
$ printf '\033]7501;state=error\a'No mark, at rest
$ printf '\033]7501;state=idle\a'Needs you, Done and Failed notify you, unless you're looking at the tab. Done and Failed stay until someone looks at the tab. What each mark means is on Get notified.
How a line is built
Each line starts with \033]7501;, then key=value pairs separated by :, and ends with \a. In printf, \033 is the Escape character and \a is the bell character:
\033]7501;state=blocked:kind=question\a- Print it to standard output or standard error. When your output goes to a file or a pipe, print it to the terminal itself:
printf '\033]7501;state=working\a' > /dev/tty. - Send every key you want shown on every line. A later line replaces the earlier one for the same job (see Report more than one job).
- The whole line can be at most 4096 bytes.
| Key | What it is |
|---|---|
state | Required. idle, working, done, blocked, error or clear. idle says the program is at rest and shows no mark. clear removes the status. |
kind | With blocked: permission for an OK, question for an answer, auth for a sign-in or token. |
progress | With working: a whole number from 0 to 100. |
msg | One line for people: what it's doing, waiting for or finished. In base64, at most 2048 bytes of text. |
title | A short label for people, in base64. Desktop notifications can name the tab with it. |
app | Your program's name, such as deploy. Used as the name when there's no title. |
id | A name for this job, when you report more than one. |
Add a message
To say what your script is waiting for, put it in msg, in base64:
$ printf '\033]7501;state=blocked:kind=permission:msg=%s\a' "$(printf %s 'Deploy to production?' | base64)"The message shows in Needs you, as in Needs your OK · build-box · Deploy to production?, in desktop tooltips, and in desktop and chaar command notifications. Phone notifications never include it.
Everyone who can see the machine sees your status
Statuses and messages go to everyone who can see this machine in chaar, not only to you. Keep passwords, tokens and other secrets out of msg and title. See Who can reach your machine.
Report more than one job
To report several jobs at once, such as a build and its tests, give each one a name with id:
$ printf '\033]7501;id=build:state=working\a'$ printf '\033]7501;id=test:state=blocked:kind=question\a'The tab shows its most urgent job, here Needs your answer. A line without id is the tab's main status. A / in an id puts one job beneath another: test/unit sits beneath test.
Clear a status
$ printf '\033]7501;state=clear\a'With no id, this clears every status in the tab. With an id, it clears that job and the ones beneath it, so id=test also clears test/unit.
chaar also clears some for you:
- At a new prompt, chaar clears Working and needs-you statuses. Done and Failed stay. This needs a shell that marks its prompts with the
OSC 133prompt mark, which most shell integrations send. A tool that stops without clearing doesn't stay Working, and a line like this you type at the prompt lasts only until the next prompt, so run it from a script. - On a full reset,
printf '\033c'clears every status, and the screen too.
Show progress the common way
chaar also reads the progress line that many other terminals understand:
| Line to print | chaar shows |
|---|---|
printf '\033]9;4;1;40\a' | Working, 40% |
printf '\033]9;4;3\a' | Working |
printf '\033]9;4;2\a' | Failed |
printf '\033]9;4;0\a' | No mark |
Don't mix the two kinds of line in one tab. Once a tab gets one of the status lines above, chaar ignores these there until a full reset.
Set the tab's title on the phone
The standard window title line gives the tab a title:
$ printf '\033]2;%s\a' 'Deploying'\033]0; in place of \033]2; works too.
On the phone, a tab nobody renamed shows this title. The desktop app and the chaar command keep the name you gave the tab, or else the name of the program running in it.
Check that the terminal reads these lines
From a program that reads its input, print:
\033]7501;?\achaar writes the same \033]7501;?\a back to the tab's input, so your program reads it like typed keys.
If a status doesn't show
- A line with a mistake, such as a missing
stateor amsgthat isn't valid base64, is dropped with no error. - The machine reads statuses about once a second while an app watches it, so a state that lasts less than that may never show.
Stuck? Ask in the Discord community.