Docs/The Director/Session cards and states
Director

Session cards and states

4 min read

Every session is a card in the Director sidebar, and the card is designed to answer one question without a click: does this session 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 session is doing, in words. The full set is listed below.
  • 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 Director, 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. Nothing outranks working: a session that is working is blue, whatever else is going on.
  • 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 at its prompt that has not taken a turn yet, nothing asked of you.
  • Yellow - being read for you. Either the Wingman is reading the finished turn, or a voice-mode session's spoken summary is still being generated. The card turns red once there is something for you to act on.
  • Purple - running in the background. The session is sitting on its own long task, such as a build.
  • Orange - transcribing. A dictated message is being turned into text and sent in.
  • Slate - sub-agent. A worker session another session is driving. Its "needs you" is muted so it never nags you - the session driving it deals with it.
  • Dark red - crashed. The agent process ended unexpectedly.
  • Gray - snoozed, exited, or indeterminate. One gray, deliberately, for all three: read the label under the name to tell a session you snoozed (Snoozed) from one whose agent process has ended (Exited) from one whose state cannot be determined (Idle).
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 session's state in words:

  • Working - mid-task, producing output (also while the agent process is still starting).
  • Needs you - stopped and waiting for your answer, a permission decision, or its next task.
  • Ready - a fresh session that has not taken a turn yet.
  • Snoozed - you set the session aside; see below.
  • Background - running its own long task.
  • Transcribing - a dictated message is being turned into text. A dictation sent from the phone first reads Uploading from phone.
  • Wingman reading - the Wingman is reading the finished turn for you.
  • Preparing voice - a voice-mode session's spoken summary is being generated.
  • Sub-agent - a worker session another session is driving, its "needs you" muted.
  • Exited - the agent process has ended.
  • Crashed - the agent process ended unexpectedly.
  • Idle - the fallback when the session's state cannot be determined.

Order and snooze

Cards stay in the order you put them - drag the status square to rearrange. And when a session should stop competing for your attention without being closed, snooze it from the card's menu: Snooze uses your default length, Snooze for picks a length on the spot, and Unsnooze brings it back. A snoozed session shows the gray square and the Snoozed label, with the time remaining beside it, and the Director stops counting it as needing you. When a snooze runs out on its own, the card carries a Snooze ended badge if the session is still waiting.

Tip
Treat red as an inbox: the header counts the sessions that need you, and working that number down answers everything that is asking for an answer.
Warning
Clearing the count is not a health check. A crashed session folds to dark red rather than red, so it counts as active and never enters that number, and a session the Gateway has not yet reported on is deliberately treated as not needing you. An empty header therefore means no session is currently reported as needing you - not that every agent is busy or done. Scan the squares before you read the Director as quiet.

Where to go next