Docs/Cockpit (browser)/The session rail
Cockpit

The session rail

4 min read

The left side of the Cockpit is the session rail: a single scrollable list of every agent session across your whole fleet - every machine, every Gateway, every Director - in one column. It is how you find the session you want and see, at a glance, which one needs you.

The Cockpit session rail listing three sessions on SOREN_NORTH, each showing Needs you, a started time, open and idle timers, a turn count, and a yellow uncommitted-changes badge reading 4 chg, 2 chg and 3 chg
The Cockpit session rail: a scrollable list of session cards, each with a session number badge, a two-line title, an activity label, and a machine name; one card is selected and two are highlighted red for needing attention

Session numbers

Every card carries a short session number - a small badge like 102 or 104. That number is the name people actually use to refer to a session out loud: in a note, in a message to a teammate, or by voice. It is stable and short on purpose, so "take a look at 104" is unambiguous. The same number shows on the card in the rail and on the card in the Fleet Map, so a session reads the same everywhere you meet it.

Reading a card

Cards are a uniform height and built to be scanned, not studied. Each one shows a two-line title, an activity label (working, needs you, snoozed), the machine the session runs on, and small badges for what is on - for example a voice badge when Wingman is running, or an amber N chg badge counting uncommitted changes in the session's working tree. The chg count is the same number the Director's own rail shows - measured once, on the Director - and the badge is absent, never "0 chg", when the tree is clean or the count is unknown. See source control and history for what the count means and its limits. Two visual states matter most:

  • Selected. The session you are currently looking at is clearly marked so you never lose your place as the list updates.
  • Needs you. A session waiting on an answer is colored red, and that attention color is kept deliberately distinct from the selected state - a card can be selected, or waiting, or both, and you can always tell which. A short timer ("just now", "waiting 8m") tells you how long it has been stuck.

For the full meaning of the colors and labels - the same vocabulary the Director uses - see session cards and states.

Ordering: My order vs Attention first

A toggle at the top of the rail decides how the list is sorted:

  • My order is the default - a stable, manual order that does not rearrange itself while you work. Things stay where you expect them.
  • Attention first groups the sessions that need you at the top, so when several are waiting you can work straight down the list.
Tip
Leave the rail on My order for day-to-day work so the list stays predictable, and flip to Attention first when you come back to a busy fleet and want to clear the waiting sessions in one pass.

Starting a new session

The + New session button at the top of the rail opens a picker for starting a session anywhere in the fleet. You choose the machine to run it on and the repository to open - pick one of your recent repos or type a path - and the Cockpit starts the session on that machine for you. You do not have to be sitting at that computer.

Screenshot coming soonThe Start a new session dialog in the Cockpit: a machine picker listing the machines in the fleet, a repository picker with recent repositories and a path field, and a Create session button
The Start a new session dialog in the Cockpit: a machine picker listing the machines in the fleet, a repository picker with recent repositories and a path field, and a Create session button

The session menu

Every card has a three-dot session menu (the same menu also sits at the top of the open session page). It holds the actions that manage the session itself, rather than steer the agent:

  • Rename - give the session a clearer name.
  • Snooze / Unsnooze - quiet a session you are not working on right now, and bring it back when you are. Snooze for offers specific lengths when you want something other than your default.
  • Handover info - the session's identity block: its name, session id, repository, Director, machine, and version. It is what you copy when you hand a session off or ask for help with it.
  • Close session - end the session for good. This one asks you to confirm first, because it cannot be undone.
Note
Closing the Cockpit tab is not the same as closing a session. The tab is just a view; the agents keep running in the Director on their machine. See keeping agents running.

Where to go next