Docs · Status
Status
Every session's tmux pane is polled, every two seconds by default
(poll_interval), and each poll resolves to one of six states.
| State | Meaning |
|---|---|
| working | The agent is busy on a turn. |
| waiting | Blocked on you: a dialog, a permission ask, or a plain-text question. |
| finished | Turn ended. An alert that clears to idle once you enter the session. |
| errored | The tool reported an error. |
| idle | Nothing running. |
| dead | The tmux session is gone. The row stays. |
Pane rules
Detection matches per-tool regex rules against the visible pane, reads the newest turn to
tell finished from waiting, and treats output that changes between
polls as working. A turn that ends without any summary line still resolves: a
working pane that goes quiet counts as finished, or
waiting when it ended on a question.
Work that outlives the turn which started it, such as a background agent, is matched by
busy_line, so a turn-end summary keeps reading as working while that
work runs. Polling continues while you are inside a session, so the statuses stay live.
Claude Code hooks
For Claude Code the status is first-hand rather than inferred. Sessions launch with a
generated --settings file whose
hooks write the lifecycle
state to a per-session status file, and the poller reads that first.
[tools.claude]
status_source = "claude-hooks"Pane rules still refine it, because hooks cannot see a plain-text question, an Esc interrupt or an error line, so a matching pane verdict upgrades the hook status. They take over entirely when the hook file is missing or stale.
Reading the list
Each row carries its status and tool inline, and a folded group keeps a count per status, so
a collapsed subtree still tells you whether anything under it needs you. Selecting a session
shows the tail of its pane on the right, which is how a waiting agent's actual
question reaches you without attaching.