States and attention
Every pane shows whether its program is working, waiting for you, or finished. The daemon keeps each state, so it's right even when no window is open.
| State | Means | Counts as needing you |
|---|---|---|
idle | At a prompt, or nothing has reported | |
running | A command or agent is working. Shows a percentage if one is reported | |
waiting | Blocked on you: a question, a permission, a password | ✓ |
failed | Ended with an error, and you haven't looked yet | ✓ |
done | Finished, and you haven't looked yet | |
exited | The program ended and the pane was kept (isc run --keep) |
Each state has its own mark in its own colour. running is a spinning ring, the only mark that moves. waiting is a ringed dot, done a tick, failed a cross, and exited a ring with a bar across it.
done and failed clear when you look at the pane: when it has the keyboard in a window that's in front.
Where a state shows
- On the pane: its header says the state in words, what the program said about it, and how long it has needed you. A waiting pane glows.
- Everywhere else the pane appears: its tab, its sidebar row, its dock chip. Hover over a mark to read the words.
- As counts, at the top of the sidebar or in the top bar: how many panes need you, and how many finished. The tray, the Mac's menu bar and
isc tuishow the same numbers. - In the sidebar's Needs you panel, at its bottom, while any pane waits or failed: each one's tile, its name in its project and what it says, in the order
Ctrl+Shift+Awalks them. Click a row to go to that pane, or right-click it for its menu. - Under the bell: press it for the list "Finished, not looked at yet". Click a row to go to that pane. Escape or a click outside closes it.
- On a folded tab or project: the most urgent state of what's inside, in this order:
waiting,failed,done,running. Unfolded, the rows beneath show their own states.
A waiting pane says what it waits for when its program tells it: "wants permission", "asks a question" or "needs you to sign in". An agent's permission question names the tool and what it would act on, such as Needs permission: Bash · git push origin main.
When the dock has more chips than room, the idle panes share one chip, such as "3 idle". Click it to open the palette. A pane with a state always keeps its own chip.
Nothing is ever reordered because of a state.
TIP
Turn off the glow with attention-glow = false. It's also left out when pane-gap = 0, since there's no gap for it to fill.
Going to the pane that needs you
Press Ctrl+Shift+A, or click the count in the top bar. You go to the most urgent pane, restored if it was minimized. Press it again to step through the rest: first what needs you, then what finished.
You can also:
- Open the palette: the panes that need you are listed first.
- Open the overview: every tab of every project, with what each waiting pane asks and for how long.
- Show only activity in the sidebar: press the pulse-line button at its head. See The sidebar.
Where a state comes from
insensical works out a state from four things. The strongest wins.
- A report. The program says it in its own terminal (see Programs that report by themselves), or an agent's hooks or a script run
isc status running|waiting|done|failed|idle [-m "what about"]. Arunningorwaitingreport stands until the next report or until the command ends. In a pane you started with a command, such asisc run -- claude, it stands until the next report or until the program ends. - What the program writes to its terminal.
- Progress (OSC 9;4): a percentage or an unknown amount is
running; removed isdoneif the pane was running; error isfailed; paused iswaitinguntil the command ends or you look. - A notification (OSC 9, 777 or 99) is
waitingwith its text, until you look. It doesn't change adoneorfailedthat was reported. - The bell, while nobody is looking, is
waitinguntil you look. It marks the pane and never sends a desktop notification. - A password prompt is
waitingand "needs you to sign in", with the line it asks on, such as[sudo] password for you:. The page's card for it has a password field. It's spotted when the terminal stops showing what you type while still taking a whole line, assudo,ssh,gitandread -sdo. It stops when typing shows again or the command ends.
- Progress (OSC 9;4): a percentage or an unknown amount is
- The foreground command ending:
doneif the pane wasrunning, or if the command ran for 30 seconds or more (or as long aslong-commandsays). This needs no shell integration. - The program itself ending in a kept pane:
failedif it exited with a non-zero status.
| Command | Does |
|---|---|
isc status explain [--pane N] | Tells you why a pane is in its current state. |
isc status clear [--pane N] | Forgets what was reported and puts the pane at rest. Use it when a pane says running or waiting for something that's gone. |
The palette has the same as "Forget what this pane's program said it was doing" (forget). Looking at a pane never clears running or waiting.
Programs that report by themselves
A program can tell its terminal what it's doing, and insensical listens. It needs no hook or setup, and works over ssh and in a container, where isc status can't reach. This is the Program Status Protocol, an escape sequence numbered OSC 7501, read at revision 0.4.
Claude Code speaks it from version 2.1.295. So can any script:
status() {
printf '\e]7501;state=%s:msg=%s\e\\' "$1" "$(printf '%s' "$2" | base64 | tr -d '\n')"
}
status working "Syncing photos"
rsync -a ~/Photos backup:/photos && status done "Photos synced" || status error "rsync failed"| The program says | The pane shows |
|---|---|
idle | idle |
working, with a percentage if it gives one | running |
blocked | waiting |
done | done, until you've seen it |
error | failed, until you've seen it |
A program can also:
- Say what it's blocked on:
permission,questionorauth. The pane shows "wants permission", "asks a question" or "needs you to sign in", inisc lstoo. - Give its name, as Claude Code gives
claude-code. If insensical has an icon for it, or you gave one under[icons], the pane uses that icon. - Report on tasks of its own, such as an agent's helpers. The pane shows the most urgent one, and the overview adds a count like "3 tasks · 1 waiting". If the program itself says done or idle while a task still works, the pane shows running, unless another task waits or failed.
- Take back what it said (
state=clear).
It outranks an agent's own hooks while it says working or waiting, and the hooks count again after it says anything else. If it has been silent while working, a hook that says waiting, done or failed is believed. Working and waiting end when the command ends at your shell's prompt. done and failed stay until you've seen them.
Good to know
- A program inside
tmuxorscreenisn't heard. - A pane can keep saying
runningorwaitingafter its program was killed, if it ran throughssh,docker execorsu, under a shell inside a shell, or in a pane started with a command that isn't a shell. Runisc status clear, choose Forget in the palette, or typeprintf '\e]7501;state=clear\e\\'in the pane. A state never ends for being silent. isc shell-integration(below) makes the shell end working and waiting at each prompt.- A shell function that reports and then waits with
waitorreadlooks like a shell at its prompt. Put the work in a script.
Commands that fail, and short commands
- A long command is one that ran for 30 seconds.
long-commandchanges that, from 1 second to 3600. - With shell integration, a failed command is
failed, with a note such as "exited with 2 after 1m 35s". Without it, a failed command shows asdone. - A short command isn't marked, even if it fails.
- An exit status of 130 (Ctrl+C) counts as finished, not failed.
To turn shell integration on:
| Shell | Add |
|---|---|
| bash 4.4 or later | eval "$(isc shell-integration bash)" in ~/.bashrc |
| zsh | eval "$(isc shell-integration zsh)" in ~/.zshrc |
| fish older than 4 | isc shell-integration fish | source in ~/.config/fish/config.fish |
| fish 4 and later | Nothing: it does this itself |
Each does nothing outside a pane. An older bash, such as the Mac's /bin/bash (3.2), is left alone. Other terminals' integrations that write the same marks (OSC 133 C and D) work too.