Skip to content

States and attention ​

Who needs you, in under a minute, with sound

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.

StateMeansCounts as needing you
idleAt a prompt, or nothing has reported
runningA command or agent is working. Shows a percentage if one is reported
waitingBlocked on you: a question, a permission, a password✓
failedEnded with an error, and you haven't looked yet✓
doneFinished, and you haven't looked yet
exitedThe 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 tui show 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+A walks 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.

  1. 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"]. A running or waiting report stands until the next report or until the command ends. In a pane you started with a command, such as isc run -- claude, it stands until the next report or until the program ends.
  2. What the program writes to its terminal.
    • Progress (OSC 9;4): a percentage or an unknown amount is running; removed is done if the pane was running; error is failed; paused is waiting until the command ends or you look.
    • A notification (OSC 9, 777 or 99) is waiting with its text, until you look. It doesn't change a done or failed that was reported.
    • The bell, while nobody is looking, is waiting until you look. It marks the pane and never sends a desktop notification.
    • A password prompt is waiting and "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, as sudo, ssh, git and read -s do. It stops when typing shows again or the command ends.
  3. The foreground command ending: done if the pane was running, or if the command ran for 30 seconds or more (or as long as long-command says). This needs no shell integration.
  4. The program itself ending in a kept pane: failed if it exited with a non-zero status.
CommandDoes
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:

sh
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 saysThe pane shows
idleidle
working, with a percentage if it gives onerunning
blockedwaiting
donedone, until you've seen it
errorfailed, until you've seen it

A program can also:

  • Say what it's blocked on: permission, question or auth. The pane shows "wants permission", "asks a question" or "needs you to sign in", in isc ls too.
  • 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 tmux or screen isn't heard.
  • A pane can keep saying running or waiting after its program was killed, if it ran through ssh, docker exec or su, under a shell inside a shell, or in a pane started with a command that isn't a shell. Run isc status clear, choose Forget in the palette, or type printf '\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 wait or read looks 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-command changes 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 as done.
  • 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:

ShellAdd
bash 4.4 or latereval "$(isc shell-integration bash)" in ~/.bashrc
zsheval "$(isc shell-integration zsh)" in ~/.zshrc
fish older than 4isc shell-integration fish | source in ~/.config/fish/config.fish
fish 4 and laterNothing: 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.