Docs · Guides
The dashboard
The web view of service, streamed over SSE at localhost:4319 — and the shape of the coming team tier. From a normal install this is the operator’s view; in a dev checkout the terminal is home: see /docs/tui.
Frozen while the hosted view is rethought
The local web app takes no new features. Everything documented on this page ships today and keeps working; what stops is growth — new panels land in the TUI, not here, until the hosted view is redesigned for teammates, non-engineers, and phones.
The data plane underneath is permanent: the snapshot the server builds, the SSE stream, and the token/wake accounting are what the hosted view will read too.
Booting it
/hands:dashboardThe skill probes /api/state first: if a Hands dashboard is already serving, it just opens the browser; if the port is free, it boots hands serve in the background; if another service owns the port, it tells you to set HANDS_PORT. You can also run it directly:
hands serve # → http://localhost:4319 (Ctrl-C to stop)The server binds localhost by default (--lan below is the opt-out) and never registers itself as an agent — it has no identity on the bus and no place on the line. It is not, however, read-only: four routes write. You can answer an escalation (POST /api/questions/:id/answer), settle an approval a sous is blocked on (POST /api/approvals/:id/settle), file feedback (POST /api/feedback), and ask a question in the Ask pane (POST /api/chat). Each of those carries its own same-origin check and rate limit, because binding to 127.0.0.1 stops a remote attacker but not another page open in your own browser. Everything else is read-only.
Writes from a non-loopback client are refused outright unless the server was started with hands serve --lan --allow-writes — pairing a phone over the LAN gets you the view by default, and the write surface only if you say so. Updates stream over SSE (/api/events): a lazy ~1-second tick rebuilds the snapshot while anyone is watching and pushes only when something actually changed.
Reading it
The top bar reads “The pass · chef: <you>” with a Live badge. Below it the app is tabbed, not one long scroll: five fixed tabs in a sidebar (a horizontal strip on mobile), plus a Roles group generated from the live roster — one tab per agent, so it grows and shrinks with hands scale. The active tab lives in the URL hash, so a tab is linkable.
| Tab | What's on it |
|---|---|
| Overview | The whole pass on one screen, in this order: The line, Needs <you>, the stat cards, then a two-column split of The rail against Today’s menu, At the pass and <you>’s list. Broken out below. |
| Chits | Every ticket ever filed, not just what's in flight — the log behind the rail. Clicking any chit (here or on the rail) opens its own page: the full ticket, its cost, and its history. |
| Token usage | Its own tab, not an Overview panel. Three stacked panels: Token burn (output tokens per pane, from Claude Code transcripts), Context length (how full each pane’s context window is, over time), and Sub-agent usage (which agent types actually get dispatched, and at what cost, over the last 7 days). |
| The book | The journal feed — commits, memories, and notes as they land on the books. The day's story, as it will read in the digest. |
| Ask | A chat pane over the kitchen’s own read tools — hands_board, hands_tasks, hands_peers and friends. Read-only: it answers questions about service, it does not run it. Needs the Agent SDK installed; without it the pane says so rather than failing on submit. |
| Roles | One tab per live agent, labelled by id. Each shows that agent's state, focus, last-seen and wake rate, plus every MCP message it sent or received. Monitor history and tool usage are stubbed “not tracked yet”. |
The Overview tab, in order
| Panel | What it shows | How to read it |
|---|---|---|
| The line | One cell per station: state dot (active / idle / offline), focus label, wake rate (wakesLastHour/h · wakes24h/24h), current ticket or “standing by”, branch, and a token sparkline — plus a Crossed wires alert when two agents touch the same file or ticket. | Idle stations reading 0/h are free. Crossed wires is the one alert worth acting on quickly. |
| Needs <you> | Escalations awaiting the chef, each with the expo's recommendation (“↳ expo recommends:”). Answerable right here — this is one of the writing routes. | This is your queue. If it's empty, nothing is blocked on you. |
| Stat cards | On the rail (live tickets, with how many are at the pass), On duty (panes online, over total), Wakes (per hour, with the 24h figure), Token burn 24h (output, with cache-read). | The kitchen at a glance. Wakes near zero with work still flowing is the system working as designed. |
| The rail | Tickets in flight, grouped by dish, each chit showing assignee, priority, approximate token cost, and its state badge (fired / cooking / at the pass / served / 86'd). | “At the pass” chits are finished work awaiting the expo's review. Click one for its chit page. |
| Today’s menu | The ranked recipes in play, each with two progress figures side by side: the recipe's own markdown checkboxes, and the formal grade (how many active criteria were graded, and how many of those were met). | Those two numbers disagreeing is the useful signal, not a bug — a criterion checked off but graded not-met is exactly what you want to see. |
| At the pass | Open questions awaiting the expo (escalated ones tagged). | Questions the expo is adjudicating — they only reach you if escalated. |
| <you>’s list | Your personal to-do list — only things the chef can do (merge clicks, approvals). | The fleet adds items here instead of doing them. |