--- name: headroom description: Budget-aware orchestration with Headroom. Use before spawning agents, dispatching bulk work, or choosing which subscription or local model runs a task. Headroom answers what each account and meter can afford right now; it never decides which model is best for the task. --- # Headroom: know your budget before you spend it Headroom reports remaining capacity per meter (account × limit family), with reset times, pace states and freshness. Capability routing stays yours, in `~/.headroom/routing.toml`. ## Setting Headroom up When installed as a Claude Code plugin, the MCP server and per-prompt quota line are already registered. Skip manual MCP and hook registration. When the user asks to set up, install or configure Headroom, run these in order and stop at the first one that fails, showing its output: 1. `headroom version`; if the command is missing, `npm install -g headroomd` (Node 22.13 or newer). If the user agrees, run `headroom setup --yes --skip-mcp` to do accounts discovery, doctor and the background service install in one pass -- it answers yes to each of those on its own and shows its output. 2. Register the MCP server in the agent that will use it, for example `claude mcp add --scope user headroom -- headroom mcp`, and confirm with a `quota_status` call. 3. `headroom doctor` once more; every non-OK line names the next command. 4. Show `headroom --json` or `headroom --agent` once and explain the pace state on each row. ## Keep the budget in sight When the user works in Claude Code, offer to put Headroom in its status bar: set `"statusLine": { "type": "command", "command": "headroom statusline --render" }` in `~/.claude/settings.json` (or `/settings.json` for another profile), adding `--chain ''` after `--render` when they already have one. That single line shows this session's own 5h and weekly percentages exactly as Claude Code reported them, plus every other principal, model-scoped meter, pace state, active lease and reserve from Headroom's own view. It is a read of the store, never a vendor call, and it is capped at 150 ms so it cannot slow a prompt down; the non-session figures on it can be one poll interval old, so keep deciding from `can`, `gate` and `route` rather than from what the bar happened to show. ## Scoped models gate on their own meter A vendor can cap one model separately from the account (Claude's Fable and Routines buckets are `:fable` and `:routines`). A YES from `gate` or `can` on `:all` says nothing about those. Before dispatching a scoped model, gate on its meter: `headroom gate --model fable --need wk:5 --owner ` (or `--meter :fable`). When that meter reads UNKNOWN the answer is no, not "use the account figure". `headroom --models` is a local token-share estimate from session logs, never the vendor meter; do not gate on it. When a scoped meter cannot be polled at all, ask the user to run `/usage` in Claude Code and paste the panel into `headroom usage --paste` (or `quota_usage_paste`); that turns the bar they can see into a real reading instead of dispatching blind. ## The rule of order 1. **Pick by capability first.** Decide which pool is best for the task from your own routing table. Headroom has no opinion on model quality and never will. 2. **Ask Headroom if that pool can afford it.** `headroom can ` returns YES or NO with the limiting meter and its pace state. Exit code 0 means yes, 2 means no. Dispatch through `headroom run` so the gate and lease bracket the launched lane, or call `quota_gate` and `quota_lease_start` yourself over MCP. Never launch a lane on a meter you have not gated. 3. **On NO, walk your fallback list** for that action class, in your order. Headroom only filters the list by budget; it never reorders it by capability. 4. **Harvest only fungible work.** HARVEST means a meter is under its straight-line burn and the capacity expires at reset. Send bulk, mechanical or rubric-judged work there. Never move a hard review or an ambiguous judgment to a pool because it has credits. 5. **Local pools follow `local_preference`.** `fallback` (default): offered only when every eligible subscription pool is CONSERVE or FREEZE. `prefer`: local first for fungible work. `never`: shown, never suggested. Local inference costs energy; that is a user choice. 6. **FREEZE is the only hard rule.** Never spawn into a frozen meter. Everything else is advice you may override, and when you do, say why in the dispatch note so Headroom's audit log has it. 7. **Protect your own meter.** Set a reserve on the meter your orchestrator itself runs on (`policy.toml`'s `[reserve]` table, e.g. `"claude-main:fable" = 10`), so the lanes you dispatch cannot spend the last of the budget you need to keep supervising them. A refusal whose reason names the reserve means stop dispatching that model, not retry with fewer points. 8. **UNKNOWN is not capacity.** A stale or failed meter blocks `can` unless you pass `--allow-unknown` on purpose. Do not assume a failed read means room. A displayed `n/a` is different: the vendor confirms that window is not enforced, so Headroom ignores it for `can` and thresholds. An UNKNOWN window may still show `last_known` (the newest fresh reading of that meter from the last 7 days, with its age) so you can see the trend behind it -- read that as history, never as a green light: `can`/`gate`/`route` already ignore it and answer NO the same as if it weren't there. 9. **A plan downgrade notice is a hard stop.** Stop all work on that vendor and tell the human. Do not use a reset credit. Dispatches stay refused until the human either restores the paid plan or explicitly runs `headroom ack plan ` for an intended downgrade. ## Commands - `headroom` : the current meters with pace state and freshness, grouped by principal for a person at a terminal and one dense line per meter in a pipe. - Agents read `headroom --json` or `headroom --agent`, never the human view: `--json` is the contract, `--agent` is the dense one-line-per-meter fallback for a plain shell call, and the grouped `--human` view exists for people. - `headroom can [--allow-unknown] [--expect ] [--lease]` : go / no-go for an action class. - `headroom --threshold 90` : exit 2 if any fresh window is at or above 90%. - `headroom events --since 24h` : resets seen, free resets granted or used, source failures. - `headroom cost []` : learned median/IQR/sample-count spent percent per class. - `headroom rate [--meter M] [--owner X] [--minutes 30]` : burn over a recent window and ETA to the limit, plus X's attributed share of it. - `headroom spend [--meter M] [--owner X] [--since 24h]` : per-owner attributed spend on a shared meter. - `headroom inbox --session ` / `headroom inbox send --to --kind --text ...` : hand-offs between orchestrators. - `headroom plan --meter M --until reset --reserve N [--target ]` : points per remaining 5h window, banked-reset advice and the plan line. Ask `quota_plan` with `target_points` before recommending a banked reset. - `headroom credits set --principal --available --expires ` : record a banked reset only when the human says one exists; never infer it. A date-only expiry is midnight UTC on that date. Never fire a reset yourself -- that is a human action in the vendor UI. - `headroom plan import ` : load a budget plan's per-session shares as advisory leases. - `headroom gate --need 5h:N [--need wk:N] [--plan] [--allowance pro_rata|fill] --owner X` : pre-dispatch check before a lane. - `headroom wait --meter M --until-reset [--max 6h]` : block until a window resets. - `headroom fill --meter M --until-reset [--lane-cost N] [--allowance pro_rata|fill] --owner X` : capacity for queued lanes and action classes before the window resets. - `headroom heartbeat --owner --every [--resume ""]` : record or refresh your own heartbeat with the daemon (`--stop` to deregister; `heartbeat list` to see every registered one). - `headroom timer set --owner --name --at --action ""` : a named wake-up the daemon delivers, once, to your inbox when due (`timer list` / `timer clear --owner --name `). - MCP tools `quota_status`, `quota_can`, `quota_events`, `quota_lease_start`, `quota_lease_end`, `quota_leases`, `quota_cost`, `quota_rate`, `quota_spend`, `quota_inbox`, `quota_plan`, `quota_gate`, `quota_wait`, `quota_fill`, `quota_usage_paste`, `quota_route`, and `quota_heartbeat` expose the same (`quota_wait` never blocks: it returns the reset time and a suggested sleep; named wake-ups are CLI-only, no MCP tool). When a lane waits for a reset or build, keep it in one blocking call instead of ending turns to poll: each turn-end wakes the orchestrator and resends its context. Use `headroom wait --meter M --until-reset --max 6h` for a reset. For a long build, run one shell loop such as `until [ -f build.done ]; do sleep 30; done`. `quota_wait` never blocks: it returns `suggested_sleep_seconds`, capped at 3600 and null when the reset time is unknown. An MCP-only lane should sleep that long in one blocking call, then call `quota_wait` again to re-check; if it is null, re-check on a sensible interval. Credit/count meters are informational, not dispatch capacity: never name one in routing or pass one to `can`, `route`, or `gate`. `quota_plan` treats only a manual entry or a fresh, unheld vendor count explicitly marked as reset availability as banked; a prepaid balance is not a reset credit. ## Leases Take a lease before fanning out work: `headroom lease start --owner --meter --expect [--class ]`. Pass `--owner ` to `headroom can` (and to `headroom route --class --owner `, which reserves the same way) so your own reservation is not counted twice, and end the lease when the work is done. Other orchestrators on this machine see active leases. ## Sharing one account with other orchestrators Take a lease per lane, not one per session: the spend ledger books each poll's actual meter movement to whoever held a lease at that moment, so a lane you did not lease spends under `unattributed` and disappears from your own numbers. Read `headroom spend --owner ` (MCP `quota_spend`) at every window boundary, and `headroom rate --owner ` mid-window, to see what your share of the shared meter really cost rather than what you expected it to. A confidence below 1 means other owners overlapped yours and the split is proportional to declared `--expect` values, so declaring one makes your own figure sharper. When a human hands you an agreed division of a window, `headroom plan import ` turns it into advisory leases the other sessions' gates already respect. Leave anything another session must act on in its inbox (`headroom inbox send --to --kind handoff --text ...`) and read your own with `headroom inbox --session ` before planning the next window; reading marks a message read, so a hand-off is acted on once. ## Host guard `can` and `gate` (CLI and MCP) carry an additive `host` object -- `{ state: "ok" | "warn" | "refuse" | "unknown", reasons, load_ratio, pty_used, pty_max, orphans }` -- alongside the quota decision: local CPU load, pseudo-terminal usage and leaked-process count on the machine you're about to fan out onto. Neither `can` nor `gate` ever refuses over it themselves; read `host.state` before dispatching more LOCAL work anyway (spawning several agent lanes onto an already-overloaded host is exactly how this repo's own P0 incident started -- see docs/concepts.md's "Host guard" section). Only `headroom run`, which actually launches a child process, refuses on its own (`state: "refuse"`, exit 2) when `policy.toml`'s `host_guard.mode = "refuse"` (the default); `"warn"` or `"off"` still launches. `host.state: "unknown"` (a probe unsupported on this platform, or one that failed) is never a reason to hold back -- treat it like any other unknown: no signal either way, not a red flag. ## Heartbeats and named wake-ups A crashed orchestrator session takes every in-session timer and watcher down with it, unnoticed for as long as nobody happens to look. Beat once per interval so the daemon -- the one process that survives that crash -- can tell "quiet because idle" from "quiet because gone": `headroom heartbeat --owner --every 5m --resume ""` at the start of a session and again on your own cadence, keeping the resume sentence current as the plan changes. Miss more than 2x that interval and the daemon records `heartbeat_lapsed`, delivered to the human the same way any other notification is; beating again closes it. Stop it explicitly (`--stop`) when the session ends normally -- an unstopped heartbeat left lapsed is a false alarm for whoever reads it next. For a wake-up at a specific time rather than a recurring beat, `headroom timer set --owner --name --at --action ""` delivers that text to your inbox once, when due -- Headroom never executes it, only delivers it. Add `--if-missed notify` (the default) when a human should also be told if you are not there to read it. ## Pacing - **Check burn before fan-out.** `headroom rate --meter M` (or the pace segment on `headroom`'s own status line, `burn 22%/h, ok 9%/h`) says whether the current rate would empty the window before its reset. A fast burn flips a window's pace state to CONSERVE even when the straight-line usage-so-far still looks fine -- that projection is the earlier warning, not a false alarm. - **`can --lease` so costs are learned.** With no `--expect`, `can` reports the learned median cost for the action class (or "unknown" the first time) plus how many more calls fit before reset at the sustainable pace. Passing `--lease` reserves the deciding meter for that expectation, so the next `can` for the same class has one more sample to learn from -- `headroom cost ` shows the running median, IQR and sample count. - **A projection CONSERVE is slow down, not stop.** It means the current rate would run the window dry early, not that the window is out of room. Prefer fungible or lower-priority work over new fan-out until the rate settles; FREEZE, not CONSERVE, is the hard stop. - **`gate` before every lane, `fill` for queued work near reset.** `gate --need 5h:N --owner X` is the per-lane pre-dispatch check; under the default `pacing = "even"` it also refuses a burst that runs far ahead of your planned share for this window, even if the raw reserve isn't crossed yet. `fill` reports how many more queued lanes (and which `routing.toml` action classes) fit before reset -- ask it when pending work needs a capacity check, rather than guessing whether one more lane is safe. Pass `allowance: "fill"` (or `--allowance fill`) only when that queued work should use the window before reset and no other work needs it; it projects open leases and recent burn to the lane end while retaining the cap. Unspent quota is information, not a target: never invent work to use it. Keep the pro-rata default otherwise. - **An unscheduled reset means capacity appeared -- re-plan, and tell the human.** `gate`, `plan` and `fill` all carry a `notices` array for 24 hours after a reset that fired before its own scheduled instant (`headroom events`/`quota_events` show it as `reset_seen` with `metadata.unscheduled: true`): `"unscheduled reset on at