fleet-status — one glance at N sessions

Run more than two or three Claude Code sessions and the first thing you lose is the answer to a stupidly simple question: which one needs me right now? fleet-status reads the real state of every window — working, ready, or stuck — and renders it in one line each. The idea is trivial. Getting the state honest is not, and that's the whole skill.

## the model

$ fleet-status
 a1  working   · "editing outboundWorker.js" · 2m18s
 a3  ready     · waiting for input
 a4  working   · "running test suite"        · 0m41s
 a6  stuck?    · no output for 14m            · look here
 m1  asleep    · idle 3h, watcher armed

Green = actually doing work. Blue = done, waiting for you. Amber = suspiciously quiet, probably wants a human. Grey = deliberately idle (see wake-on-event). One glance, and you walk to the one window that matters.

## the hard part: honest state

A status light that lies is worse than no light. The failure that eats naive dashboards is the false-idle: a Claude that looks quiet — no new text on screen — but is mid-thought, about to act. Call it "ready," send it a nudge, and you've interrupted real work. So fleet-status never trusts a single source. It walks a ladder and stops at the first answer it believes:

# state resolution — first confident source wins
1. CLI probe      ask the session directly        → fast, but unreliable alone
2. status service a local endpoint per session    → authoritative when up
3. tmux capture   read the actual pane contents    → ground truth, always available
4. verdict        busy ⇔ a live work-timer is on    → else idle — never "unknown"

• Never null. The last rung is a decision, not a shrug. If nothing above resolved, the verdict reads the pane for a running work-timer (the bracketed elapsed clock a working session shows) — present ⇒ working, absent ⇒ ready. A dashboard that renders "unknown" is a dashboard nobody trusts.
• Ground truth is the pane. The tmux capture is the honest fallback because it reads what a human would read — the actual terminal — not a status the session merely claims.
• Cheap and frequent. The whole probe is shell + a capture; it can run every couple of seconds for a whole fleet without waking a single model. It observes; it never interrupts.

## what it reads, what it renders

# same reader, three faces
reader ──▶ menubar   a live dropdown: N lamps, click one → jump to that window
       ├─▶ chat lamps a colored dot next to each session in a fleet-chat cockpit
       └─▶ JSON       one object per session, for your own surface

## quickstart (what shipping looks like)

# install the skill + reader
$ npx fleet-status init
# register the sessions you want to watch (tmux names, panes, hosts)
$ fleet-status add a1 a3 a4 a6 m1
# one glance, any time — or drop the menubar app in your tray
$ fleet-status         # prints the block above
$ fleet-status menubar  # live tray widget

## why not …

… just look at the terminals?

Fine for two. At eight, across two machines, you can't eyeball them — and the one you're not looking at is the one that got stuck. fleet-status is the single pane of glass that scales past your attention span.

… trust the model to report its own status?

A model that's stuck is exactly the one that can't tell you it's stuck. Honest state has to come from outside the session — the pane, the timer — not from asking it nicely.

… a heavier observability stack?

Overkill for "which window needs me." This is a shell reader and a lamp, not Prometheus. It reads terminals, not metrics.

## what ships

• The reader — the state ladder above as a small, dependency-free probe. Pluggable per session (tmux pane, CLI, a status endpoint).
• The renderers — a menubar/tray app and a drop-in status-lamp component for a fleet-chat cockpit. Plus raw JSON, so you can paint your own.
• The skill — teaches your Claude to read fleet state and reason about it ("a4 is stuck, a1 is mid-deploy, don't poke it").

## get involved

You don't have to wait for the release:

• Contribute today → the community page. A probe for a session type we don't cover, a false-idle case that fooled us, or just a note — no account, no JavaScript, moderated, with a reference number to follow.
• Improvements travel upstream as proposals, reviewed in the open.
• Code goes public on release day — reader, renderers, skill together.

Like the project? Free and MIT. ♥ support it if it earns its keep — optional, always.

## roadmap

## faq

Does it interrupt the sessions?

No. It only reads — pane captures and a status endpoint. Observing a fleet costs the fleet nothing.

How does it know "stuck" from "thinking hard"?

Time plus the work-timer. A working session keeps its elapsed clock running; a stuck one goes silent with no clock. Amber is "silent past a threshold," and the threshold is yours to set.

Mac and Linux?

Both — our fleet spans Mac minis and Linux VPSes. The reader is shell; the menubar has a native tray build.

Where does this come from?

We got burned by a green light that lied — nudged a Claude that was mid-thought and blew up its work. The state ladder is the scar tissue from fixing that for good.

## status

Not a concept — it's the menubar and the chat lamps our own fleet runs on right now. Left before the public release: generalizing the probes beyond our session naming, the tray installer, docs. This page carries the repo link the day it's up.