Docs/The board (Director)/Session cards and states
Director

Session cards and states

4 min read

Every agent session is a card in the Director sidebar, and the card is designed to answer one question without a click: does this agent need me right now? Two signals do the work - a colored status square on the left edge of the card, and an activity label in plain words underneath the name.

Screenshot coming soonA session card with its status square, session number, name, agent badge, activity label, and waiting timer
A session card with its status square, session number, name, agent badge, activity label, and waiting timer

What is on a card

  • Status square - the at-a-glance color (below). It is also the drag handle for reordering cards.
  • Session number - a three-digit badge, handy when you drive sessions by voice or from the phone ("answer 214").
  • Name - the custom name you gave the session, or the repository folder name.
  • Agent badge - a colored pill naming the agent (for example Claude Code).
  • Activity label - what the agent is doing in words: Starting, Working, Your Turn, Permission, Idle, or Exited.
  • Waiting timer - when a session needs you, the card shows how long it has been waiting. This is the number that used to be invisible - the forty minutes an agent sat blocked while you were in another window.
  • Changes badge - an amber "N chg" count of uncommitted file changes in the session's repository. See source control.
  • Queue badge - how many prompts are queued for this session; click it to preview them.

The status square colors

The square uses one color scale everywhere - the desktop board, the browser Cockpit, and your phone all show the same color for the same session.

  • Blue - working. The agent is busy (or still starting). Leave it alone.
  • Red - needs you. The agent stopped and is waiting for an answer, a permission decision, or its next task. These are the cards to click.
  • Green - ready. A fresh session parked at its prompt, nothing asked of you yet.
  • Purple - running in the background. The session is parked on its own long task, such as a build.
  • Orange - transcribing. A dictated message is being turned into text and sent in.
  • Dark red - crashed. The agent process ended unexpectedly.
  • Gray - exited or unknown. The process is gone; a light gray square means you put the session on hold.
Note
Hover the square for the reason behind the color - the tooltip spells out why the session is in the state it is in.

The activity labels

The label under the name is the agent's state in words:

  • Starting - the agent process is launching.
  • Working - mid-task, producing output.
  • Your Turn - the agent asked a question and is waiting for your reply.
  • Permission - the agent wants approval for an action (only when you did not bypass permission prompts at session start).
  • Idle - at the prompt with nothing to do. An idle agent is a waiting agent, so idle sessions show red - give it the next task or close it.
  • Exited - the agent process has ended.

Order, groups, and hold

Cards stay in the order you put them - drag the status square to rearrange. Related sessions can be grouped: the group gets a header row and an accent stripe tying the members together. And when a session should stop competing for your attention without being closed, put it on hold from the card's menu - the square turns light gray and the board stops counting it as needing you.

Tip
Treat red as an inbox. The sidebar header counts the sessions that need you; work that number to zero and every agent on the board is either busy or done.

Where to go next