The fleet map
5 min read
Once more than one session is running, the question stops being "what is this session doing" and becomes "is anything waiting on me". The fleet map answers that in one picture: every machine, every session, and who needs you - across your whole fleet rather than one window.
This takes about five minutes. You need at least one session running; the map is more useful the more you have, but it reads the same either way.
Open the fleet map
In the Cockpit, choose Fleet Map in the left rail. The map remembers whichever grouping you used last, so before reading on, make sure By machine is selected in the row of buttons at the top right - that is the view this tutorial reads. The line along the top is then the whole answer before you look at anything else: how many sessions exist, how many machines they are spread over, and how many repositories they touch. When sessions are busy, a blue working count joins that line; when any session is waiting on you, a red needs you count appears at the end.
The red number is the thing to look for. If it is there, that many sessions are waiting for you. If there is no red number at all, nothing needs you and you can close the tab. That is the point of the page.
Read the shape
Underneath, the fleet is drawn as a tree. Your Gateway sits at the top, each machine hangs off it, and each session is a card on its machine. A card carries the session number (when the session has been assigned one), the session's name, and its state in words, next to a relative time - "2m" means the session was last active two minutes ago. It is the same time on every card, whatever its state, not a count of how long a red one has been waiting. The card's other tags - which coding agent is running it, which model, which repository or machine - adapt to the grouping, so a card never repeats what its own column heading already says.
The coloured dot is the state, and the key along the bottom tells you which is which. Red is the one that matters: it means the session has stopped and is waiting for a human.
Group it a different way
The buttons above the map re-draw the same fleet around a different question. There are eight groupings: By machine, By director, By repository, By working tree, By agent, By model, Fleet list, and Missions. Three of them cover most days: By machine answers "is one computer overloaded", By repository answers "how many sessions are in this codebase at once", which is the one that catches two sessions about to collide, and By agent answers "what am I actually running".
Click between two of them now. Nothing changes about your fleet - only how it is arranged in front of you. One grouping changes the top line too: on Missions it counts missions and standalone sessions instead of machines and repositories, though the working and needs-you counts still behave the same.
Find one session and go to it
Type part of a name into the search box - every grouping except Missions has one - and the map narrows to matching sessions. Click a card to open that session and answer it. That is the whole loop the map exists for: spot the red one, click it, deal with it, come back.
Next
For what each grouping does in detail, how the fleet list differs from the map, and what an unreachable Director looks like, see The Fleet Map in the Cockpit reference. To reach all of this from somewhere other than your desk, see Your whole fleet in a browser tab.