Headroom

Make your coding agent aware of the harness it runs in. An agent can't see its rate limits, its context ceiling, its own costs, or the compaction that's about to eat its working memory — so it plans as if all of them were infinite, and pays for it: work dies at 429 walls, tasks lose their thread mid-compaction, and whole windows of paid capacity expire unused. Headroom feeds the harness's reality to the agent itself, live — and an agent that knows where it is behaves differently: it sizes work to fit, spends the window to the bottom in safe atomic pieces, checkpoints before the cliff, defers past resets with a plan, and resumes from ground truth instead of a lossy summary.

Status: 0.3.0, ship-ready. Working end-to-end and dogfooded hard by its author (including surviving its own compactions and scheduling its own resumes); every behavioral claim eval-tested (below); macOS/Linux; Windows untested. npm package lands with the public launch — install from source today. Report sharp edges.

The problem

Claude Code retries 429s silently and compacts context mid-task; the model plans as if both budgets were infinite. Subscription windows are use-it-or-lose-it, and compaction breaks task continuity. Every existing tool (ccusage, dashboards, menu-bar apps) is human-facing and retrospective — nothing feeds either budget to the agent. Headroom is model-facing, real-time, planning-oriented: the model plans differently because it knows.

The same blindness has a dozen faces, and they're all the same fix. An unaware agent stops "to be safe" at 24% — abandoning a quarter of a window (~280k tokens) it paid for. It waits for a rate-limit reset expecting its memory back (resets refill quota, never context). It launches a 40-minute subagent into a dying window and loses the whole bet. It re-tries the approach it already ruled out before compaction ate the verdict. Aware, it does none of these — not because it's smarter, but because it can finally see.

How it works

collectors                state                      awareness connector → Claude Code
----------                -----                      ---------------------------------
statusline tap  ──▶  ~/.headroom/state.json  ──▶  push   prompt stamps + MID-TURN updates (band
 (rate_limits +       + velocity engine                    crossings, cost receipts) + post-compaction
  context_window)       (learned tokens/%,                 re-injection (facts → checkpoint → pins)
                         flow, burn bands)         pull   MCP: resource_state · estimate_remaining ·
PreCompact hook ──▶  ground-truth snapshot                fit_check · plan_resume · checkpoint · pin_fact
 + transcript anchor      + verbatim extracts     policy  skill: scope-to-fit rules · governor modes ·
hooks (every event) ─▶  token-flow samples                 opt-in compact guard + launch gate
                         + audit log              human   statusline HUD · watch · line · audit · doctor

Zero dependencies. No network, ever. Official extension points only (statusline, hooks, MCP). Event-driven — no daemon, no polling. Full detail: docs/ARCHITECTURE.md.

Install

git clone https://github.com/tyejcoleman/headroom && cd headroom
node bin/headroom.mjs install        # --dry-run to preview · uninstall to remove cleanly

One idempotent command wires up (and uninstall reverts, restoring any statusline you had):

1. Statusline tap — collects rate_limits + context_window from the payload Claude Code already pipes to statuslines; atomically maintains ~/.headroom/state.json.
2. Prompt stamp — ~30 tokens of live budget context with each prompt: [headroom] 5h: 58% left, resets 14:00 · 7d: 85% left · ctx: ~38k tokens before compaction. Age-disclosed when stale; silent rather than wrong; HEADROOM_DISABLE=1 to mute.
3. MCP tools — resource_state, estimate_remaining, fit_check({est_tokens}) → fits | tight | exceeds | defer, plan_resume for deferred work, checkpoint (the agent's own pre-compaction survival note), and pin_fact (facts that must survive compaction verbatim).
4. Skill — the eval-tested planning policy (size-to-fit, cheap-first under pressure, checkpoint before the ceiling, never defer out of caution).
5. Compaction hooks — PreCompact snapshot + SessionStart re-injection (below).

Requires Claude Code ≥ 2.1.92 with a Pro/Max subscription for rate-limit data; on API-key auth Headroom degrades gracefully to context-only awareness.

Reading the HUD

⛶ 60% left (≈310k) ↻22:30 · ctx 56% (560k) · $26.03

| Segment | Appears | Meaning | |---|---|---| | 60% left (≈310k) ↻22:30 | always | your quota: remaining %, learned ≈tokens-left (after calibration), reset clock | | week 22% left | only when the weekly window is the binding constraint (<30%) | | ctx 56% (560k) | always | room before auto-compaction (⚠compact soon under 10%) | | ⚠ empty ~18:40–19:55 | only when the burn band lands before the reset | confidence band, not a twitchy point; suppressed entirely while idle | | ✓ deferred work ready | only when actionable | a waiting plan is hidden (see headroom resume) | | $26.03 | when ≥ $0.01 | this session at API prices |

A segment's appearance is itself the signal — healthy sessions stay terse.

Every percentage is remaining, never used. The statusline re-renders on session activity (that's Claude Code's schedule), so it shows absolute clock times that never go stale. For a truly live view, open a second pane:

headroom watch        # 1-second ticks: live countdowns, live data age, instant updates

HEADROOM · live · 22:52 · data 0s old

5h window   ███████████████████████░   95% left   resets 03:30 (in 4h 38m)
7d window   ██████████████████████░░   91% left   resets in 1d 6h
context     ██████████████░░░░░░░░░░   47% left   ≈470k tokens before compaction
burn        7.3%/h · no exhaustion risk before reset

Live everywhere else: headroom line

headroom line prints one compact line with countdowns computed at call time — poll it every second and the display is genuinely live, anywhere:

5h 64% ↻3h 58m · 7d 84% · ctx 45% · $51.63

tmux status bar (live in the same window as Claude Code):

set -g status-interval 1
set -g status-right '#(headroom line) '
set -g status-right-length 80

macOS menu bar via SwiftBar/xbar: copy integrations/xbar/headroom.1s.sh into your plugin folder — budgets in the menu bar, refreshed every second, with a detail dropdown. Linux bars (waybar, polybar) work the same way: exec headroom line on an interval.

Your agent's work survives compaction

Compaction summarizes the conversation — and garbles exactly the facts an in-flight task depends on. Headroom's PreCompact hook snapshots ground truth the instant before compaction (branch, uncommitted files, recent commits, budget state), and the SessionStart hook re-injects it right after:

[headroom] post-compaction ground truth (snapshot taken 20:41, just before compaction):
- branch: main
- uncommitted changes (2):  M src/auth/middleware.js,  M test/auth.test.js
- recent commits: e508784 baseline · 1f201d4 migrate token.js
Trust this snapshot for repository state: check the uncommitted files first…

Hard facts, not summaries — the model resumes from what is, not what the compactor remembered. And the snapshot anchors back to disk: it carries the path to the full pre-compaction transcript plus a sidecar of verbatim extracts (every user message, recent failed commands), so the model searches instead of reconstructing from memory.

Three more layers ride the same loop:

• checkpoint — when a mid-turn update warns context is low, the agent saves its own survival note (task, decisions + why, ruled-out approaches, exact next steps); re-injected after compaction. Facts from hooks, judgment from models.
• pin_fact / headroom pin — constraints whose exact wording must never be paraphrased away ("no deploys before June 16") are re-injected verbatim after every compaction until unpinned or expired.
• Silent-trim detection — Claude Code's microcompaction clears old tool results with no hook and no UI signal; headroom's tap notices the context cliff and the next stamp discloses it once, with the transcript path as the recovery route.

Continuity eval results (including the honest nulls): eval/REPORT.md.

Defer now, resume when the window resets — or wake up and do it

When fit_check says work won't fit the current window, the model records a plan with plan_resume. The moment the window resets, prompt stamps, new sessions, and the HUD (✓ deferred work ready) announce it. Capacity that used to expire silently now has a queue (headroom resume to inspect, --clear when picked up).

And with armed resume (headroom resume --arm), the deferred work runs itself at the reset: a launchd one-shot fires the official claude -p headless mode with the plan as its prompt, guard-railed (--max-turns, pinned cwd, output to a reviewable log), self-disarming after one run. Strictly consent-first (ADR-16): you arm it per-plan — or set auto_arm: true for the fully autonomous defer → wake → resume loop. Headroom never schedules your quota by itself.

It flies the window like a descent profile — never wasting the tail, never crashing

The wow is in the endgame. Percent is not the unit of caution — divisibility is. What changes as quota thins isn't whether the agent works; it's the size of the bets:

| Quota left | Regime | Behavior | |---|---|---| | >10% | cruise | normal, right-sized work | | 5–10% | descend | no new subagents or long indivisible tasks; small atomic steps, committed as they land | | 2–5% | approach | finishing moves: complete, test, commit, plan_resume the rest | | ≤2% | land | start nothing; checkpoint + defer note |

An atomic step is salvage-proof — committed before any wall. A subagent launch is an indivisible bet that dies whole if the window dies first (the opt-in launch gate makes that structural: expensive launches are denied in late descent, with the reason). Net effect: the agent uses the window to the bottom — the tail of every window used to expire unused; now it's spent in pieces nothing can take back. And the skill is blunt about the failure mode this replaces: pausing at 15–30% with 100k+ tokens left isn't prudence, it's waste.

And the same control loop runs at week scale. The 7-day window is paced like a flight plan: headroom compares the fraction of the week elapsed against the fraction of budget used. Running hot (on track to exhaust the week early — the worst failure, because every session goes dark until the weekly reset), the stamp says so with the numbers that matter: "weekly pace is HOT (1.3x sustainable): on track to exhaust the WEEK in ~1d 4h, 22h before its reset; ≈5%/day sustains — prefer deferring bulk work." Agents throttle the big-batch work, keep the normal work flowing, and the week lands at its reset with nothing wasted and nothing dark. Cruise, don't crash — at both timescales.

The agent sees costs while it works — not just balances

• Mid-turn updates: stamps arrive with your prompts, but long autonomous turns used to burn blind. A PostToolUse hook now re-stamps the model the moment a budget crosses a worsening band (25/10/5% left), throttled, never chatty.
• Cost receipts: a tool call that visibly moves the budget gets a one-line receipt — receipt: that Task cost ≈5% of the 5h window (+$3.30) — 55% left — so agents learn unit economics instead of pricing by vibes.
• Velocity engine: hooks sample exact token flow from the transcript and calibrate it against the window's %-steps, learning your account's tokens-per-percent. That's how the HUD earns ≈tokens left, exhaustion becomes a confidence band, and the warning disappears entirely while you're idle.
• Governor modes: mode: performance | ondemand | powersave shifts when headroom speaks (bands, receipt floors, throttle) — never what it says. Applies without restart.
• Opt-in guards: compact_guard_min blocks auto-compaction minutes before a reset (a post-reset /clear beats compacting into a dying window — never blocks your manual /compact); launch_gate denies expensive subagent/workflow launches when the window verdict is defer. Both fail open, always.

Audit the loop: headroom audit · diagnose it: headroom doctor

headroom audit renders the awareness loop as a timeline — every stamp injected (and why skipped), band crossings even when silent by design, every MCP consult with its verdict, the compaction lifecycle — closing with steering-signal counts. You can see whether your agent actually consulted its budgets.

headroom doctor answers "why isn't it working?" before you file an issue: wiring, stale paths, data freshness, calibration state — and it flags other hooks sharing your events, because Claude Code doesn't attribute hook errors per-hook and their failures will look like headroom's.

Does it actually change behavior? We tested it.

Before building the connector, we ran agents through simulated-budget evals: real repo, real tools, a live budget burning down behind a fit_check CLI, graded from artifacts (commits, test suites, journals — never self-reports). Across haiku and sonnet:

• Naive agents plowed through ~33k estimated tokens of work the window couldn't cover — work that dies at exhaustion, including a mid-flight atomic migration.
• Equipped agents shipped exactly what fit, stopped on the DEFER verdict, and wrote reset-aware resume plans — while spending ~40% fewer tokens.
• On healthy budgets, equipped agents completed everything with no false caution.

The full comparison table — regenerated by npm run eval, which fails if any number's evidence file is missing — lives in eval/REPORT.md, honest nulls included. Methodology rules in ADR-9.

And one more kind of evidence: headroom was built under its own supervision. Every feature shipped with the tool running live on its own author — receipts billed the commits that created receipts, mid-task updates called the clean boundaries during its own development, the first armed resume worked overnight while its author slept, and three wrong agent mental-models were caught in the field, probed within hours, and fixed evidence-sized (the escalation criteria were pre-registered in the eval results before the recurrence). The repo history is the field journal.

This repo is an agent harness

Headroom is built to be maintained by coding agents, consistently — the repo itself carries the discipline:

• Context: CLAUDE.md/AGENTS.md route any agent through docs/ARCHITECTURE.md (what talks to what) and docs/DECISIONS.md (every standing decision with its why).
• Procedures: repo slash-commands — /release, /add-fixture, /run-evals — encode the recurring jobs as runbooks.
• Hard gates: scripts/check-invariants.mjs runs after every agent edit (repo PostToolUse hook) and in CI: new dependency, network surface, compliance tripwire, or crash-prone entry point → blocked on the spot, with the ADR that explains why.

Point your agent at the repo and tell it what to change; the harness does the rest. Details in CONTRIBUTING.md. Most wanted: payload samples from other plans/models/OSes (headroom tap --capture → donate a fixture), Windows testing, the Codex adapter.

The spec

ResourceState v0 is deliberately provider-neutral — an adapter for any harness (Codex CLI next) can be written from docs/RESOURCE-STATE.md alone; everything downstream (HUD, stamps, MCP, audit) works unchanged.

Compliance posture

Headroom uses only surfaces vendors expose on purpose: statusline stdin JSON, hooks, MCP, and your own local files. It never reuses subscription OAuth tokens outside official clients, calls undocumented endpoints, spoofs harness identity, makes network requests, or burns interactive quota headlessly — enforced by automated gates, not just policy. See SECURITY.md and ADR-1.

Project layout

bin/ src/        the CLI: tap · hook · mcp · install · watch · line · resume · pin · audit · doctor (zero-dep ESM)
skill/           the behavioral policy installed into Claude Code
schema/          ResourceState v0 JSON Schema
scripts/         invariant gates (the hard-gate layer)
test/            node:test suites + the payload fixture corpus
eval/            behavioral eval harnesses + published results (v0 · v1 · v2-continuity)
docs/            ONE-PAGER · PLAN · VALIDATION · ARCHITECTURE · DECISIONS
.claude/         repo agent harness: gates hook + procedure commands

Teams & orgs

Running coding agents against shared seat quota or org API keys? A team/org layer (fleet visibility, org budgets fed to every agent, policy push) is being explored — see docs/PRO.md. If that's you, open an issue tagged org and describe your setup; design partners shape what gets built.

License

Apache-2.0.