---
title: "Status"
description: "Where each session's colour comes from: Claude Code hook events, per-tool pane rules, and how a turn is judged finished or waiting."
canonical: "https://agent-manager.dev/docs/status/"
last-updated: "2026-08-21"
section: "Documentation"
source: "agent-manager"
---

# Status

Every session's tmux pane is polled, every two seconds by default (`poll_interval`), and each poll resolves to one state, which the row carries as a colored mark.

| Mark | 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, or on `.`. |
| ✕ | errored | The tool reported an error. |
| ○ | idle | Nothing running. |
| ✕ | dead | The tmux session is gone. The row stays. |
| ◌ | starting | The pane is still launching. |

## 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 or shell, is matched by `busy_line`, so a turn-end summary keeps reading as `working` while that work runs. A usage or rate-limit banner (`limit_line`) is `errored`. 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](https://docs.anthropic.com/en/docs/claude-code/hooks) write the lifecycle state to a per-session status file, and the poller reads that first.

`config.toml`

```toml
[tools.claude]
status_source = "claude-hooks"
```

A `StopFailure` of `rate_limit` writes `errored`. 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.

> **Killed and archived sessions** A session with no window left shows the snapshot taken while it still had one, so the row still says what the agent was doing when it stopped.

## Notifications

When a session's status flips to `waiting` or `errored`, the manager fires one notification with the session name, tool and state: once per transition, never per poll. Settings has a `notifications` row that silences them (on by default) and a `notify on finish` row that adds `finished` transitions (off by default).

On macOS the desktop path gives waiting, finished and errored distinct sounds. Linux sends matching hints through `notify-send`. Inside Ghostty or cmux the state travels as an OSC 777 escape to the drawing terminal, which also reaches you when the manager runs on a remote host over SSH. Other terminals use the OS desktop path; a headless box or WSL installation without one falls back to the terminal bell.