Docs · Reference
Token usage
Running several Claude Code instances multiplies your token bill — so Hands treats tokens as a first-class operational concern: burn is measured from the source of truth and shown to you live, and the coordination layer is designed so idle agents cost nothing.
Seeing it: real numbers, not estimates
The dashboard’s Token burn panel doesn’t estimate anything. It reads Claude Code’s own session transcripts — ~/.claude/projects/<encoded-cwd>/<session>.jsonl — and sums the usage block (output, input, cache-read) of every assistant message. The MCP server itself burns nothing; the series are the panes.
- —Per station, per turn. One line per pane (the expo and each station), bucketed in 15-minute intervals over a 24-hour window. Streaming re-emits are deduplicated by message id.
- —Sub-agent calls included. Each Agent-tool call writes its own transcript under
<session>/subagents/; those fold into the same buckets, and the “Recent sub-agent calls” list itemizes each one with its approximate cost. - —Per ticket. A ticket’s cost on the rail is its assignee’s output tokens over the interval it was being worked — so you can see what a dish actually cost to cook.
- —Wakes, separately. Real wakes are logged and shown per station (
wakesLastHour/wakes24h) — the count of full-context turns the coordination layer caused, as opposed to the work itself.
recent sub-agent calls
station-1 general-purpose: write auth-refactor tests~21k
station-1 Explore: map the auth routes~23k
expo Plan: judge the auth-refactor plan~6.0k
Spending less: efficiency by construction
The unit of coordination cost is the wake — one full model turn over an agent’s entire accumulated context. Hands doesn’t ask agents to be frugal; the system is shaped so waste is structurally hard:
| Mechanism | What it saves |
|---|---|
| Parked stations cost zero | An idle station is a tail process watching a file — no polling loop, no model turns, nothing on the bill until a notify line lands. |
| Strict pass discipline | Station-to-station chatter and broadcasts are rejected before anything is written — a blocked send never wakes anyone. The expo is the only fan-out point. |
| Non-waking FYIs | hands_send({ wake: false }) delivers on the next natural drain. Anything that can wait, waits — without a turn. |
| Burst suppression | Ten messages during one busy stretch produce one wake, not ten — an undrained recipient isn't re-notified, and one drain returns everything. |
| One bundled read | hands_board({ full: true }) is a single call for tasks + questions + the menu digest, and its stateHash lets the expo’s ~15-minute review skip entirely when nothing changed. |
| Quiet board deltas | The per-prompt hook injects nothing at all unless something actually changed — ambient awareness that costs zero context on quiet turns. |
| Sub-agent economics | The expo's default executor is a sub-agent: a fresh context sized to the task that returns once and dies — versus a station turn, which replays that station's entire accumulated context, plus a wake each way. |
| Distilled context, not growing context | Role pages in the books are rewritten in place, never appended — standing knowledge stays dense instead of accreting. |
| Scheduled compaction | Stations evaluate an hourly marker on fully idle wakes and schedule /compact — after distilling their books — so long-lived contexts get trimmed on the system’s schedule, never mid-ticket. |
| Long heartbeats only | The Monitor is the wake signal; fallback timers are 15 minutes (expo) to 20–30 minutes (stations). No short cadences — “idle ticks are pure overhead.” |
“The economics pick the executor, never habit… if the work fits one dispatch-and-return, it’s a sub-agent. A station has to earn its standing context through persistence, ownership, or write-isolation.”