v0.2.15

Fixed

• A usage change of less than one percentage point (for example 0.007% to 0% just after a scheduled rollover) is no longer reported as a free reset.

v0.2.14

Changed

• Claude usage is read through Claude Code by default: the statusline snapshot first, then Claude Code's own /usage (at most every 10 minutes per profile, run whether or not a snapshot is fresh, and the source of the scoped weekly meters). The direct usage request is opt-in with claude_probe = true in policy.toml and is used only when no other reading is available. To see live figures between /usage runs, set your Claude statusLine to headroom statusline (or chain an existing one with --chain); headroom status and headroom doctor show this as one line. Headroom never edits your Claude settings.
• Requests to vendor services identify as headroomd/<version>.
• antigravity_keepalive now defaults to false.

Added

• claude_probe setting in policy.toml.
• Claude source native:claude-usage (Claude Code's /usage report), including the scoped weekly meters.
• headroom statusline keeps a snapshot fresh only while its session makes requests, and never lowers a figure within one reset window.

Removed

• The experimental Antigravity model list and unused remote Antigravity and Gemini readers. antigravity_model_catalog in an old policy.toml is ignored. Local Antigravity quota reading is unchanged.

Fixed

• Documentation: SECURITY.md wording on design goals and the Windows session file; third-party notice for SweetCookieKit.

v0.2.13

Added

• Reset history in the dashboard: per meter, the weekly (daily or longer) resets of the last 30 days, each marked scheduled, banked free reset, or early by the vendor, with the usage it gave back. The HTML report has a "Did a limit reset early?" section, and headroom dashboard prints one summary line per meter.
• Gauge mark icons docs/assets/mark-gauge-light.svg and docs/assets/mark-gauge-dark.svg.

Fixed

• The release job now polls the npm registry for the published version for up to 15 minutes before publishing to the MCP Registry (#170).

Security

• vite updated to 8.3.5 (GHSA-vfpm-58rq-9qcg, dev dependency) (#172).

v0.2.12

Changed

• Claude's scoped weekly limit (Fable and other model-scoped buckets the vendor flags inactive but still reports a percent for) is now labelled "separate weekly limit, unconfirmed: shown for visibility only" and carries metadata.unconfirmed: true beside metadata.vendor_active: false. It stays a soft window. status and line show claude-main:fable wk 41% (unconfirmed) with no pace state. A targeted can, gate, route or run on it is refused as UNKNOWN (never dispatchable, even with --allow-unknown) and points at <principal>:all; global scans and plan skip it.
• JSON contract, additive only: the new reason text, metadata.unconfirmed, and an optional unconfirmed array on line.json.

v0.2.11

Added

• headroom notify --text "<message>" [--kind <slug>] [--every <minutes>] [--ignore-quiet-hours] sends a message of your own through your notification channels, so other tools can reach you through Headroom. It repeats at most once per --every minutes for each kind, waits out quiet hours unless told otherwise, works without the daemon, and exits 0 sent, 1 nothing sent, 2 usage error, 3 suppressed, 4 deferred.

v0.2.10

Added

• Claude Code plugin: install with claude plugin marketplace add Apertur3/headroom, then claude plugin install headroom@headroom. It bundles the Headroom skill, MCP registration and a per-prompt quota line. Using it with headroom hook install does not print the line twice; install headroomd first.
• MCP Registry listing metadata under io.github.Apertur3/headroom, with release publishing through GitHub OIDC.
• A shorter README opening with install commands and a demo GIF reference.
• npm search keywords for Claude Code, MCP servers, the Model Context Protocol, Codex CLI and usage limits.
• Unscheduled reset messages now show how many free resets are still banked and their expiry when known (#157).

Fixed

• macOS and Linux: headroom install-service after an upgrade now restarts a daemon that still runs an older version, instead of saying "already installed and running" and leaving the old code in place. It also restarts a daemon too old to report its version, and exits non-zero unless the new version answers. Windows already did this.

v0.2.9

Changed

• Lease spend is now recorded per meter window instead of one number summed across the 5-hour, weekly and rolling windows. A lease's headline figure comes from the shortest percent window, and each lease says how sure that figure is: resolved, bounded, unresolved, unattributable or legacy. A lease that ran alone between two fresh readings gets an upper bound (spent_percent_bound), which learned costs may use and label as an upper bound. Leases that shared an interval stay unattributable. Existing leases are marked legacy and no longer train learned costs, so learned costs may show unknown until new leases come in. New JSON fields: spend_resolution, spent_percent_bound, spend_window_minutes, spend_windows, and on learned costs basis and bounded_sample_count; nothing was removed.

Fixed

• macOS: headroom install-service after an upgrade no longer fails with "Bootstrap failed: 5: Input/output error" and leaves the daemon stopped. It now unloads the old service and waits until launchd has let go of it before loading the new one, retries once if launchd still refuses, and exits non-zero (naming the manual launchctl bootstrap command) if the daemon is not answering afterwards.
• headroom line now shows every meter of an account that has a fresh reading, for example both antigravity:gemini and antigravity:claude-gpt when both are current, instead of marking the whole account UNKNOWN because one meter is stale or held. An account reads UNKNOWN only when none of its meters is fresh, and UNKNOWN accounts now come after the ones with a reading.
• Windows: the "Headroom Daemon" task no longer has Task Scheduler's default 72 hour run limit, which silently stopped the daemon after three days; it also restarts after a crash (up to 3 times, a minute apart). Run headroom install-service once to replace the existing task.
• headroom doctor on Linux and Windows no longer tells you to reinstall for macOS; it says the native reader (Antigravity) is macOS-only.

Documentation

• README and quickstart: MCP registration and a real Claude login read are now verified on Windows 11, and the keychain grant step is marked macOS-only.

v0.2.8

Added

• Antigravity models from complete local agy reads now appear in headroom models and use the existing new-model alerts. The first catalog read seeds silently.
• A native one-line quota status for agents (#149). After each poll the daemon writes line.txt and line.json to the Headroom home (atomic, mode 0600): one binding window per account with its pace state, burn per hour and time to reset, plus Codex free resets. Account names are reduced to [A-Za-z0-9._:-], and a stale or failed reading makes its account UNKNOWN, never a number.
• headroom line [--json] [--max-age <seconds>] prints that line, marked STALE (<age> ago) past two poll intervals, or says there is no fresh reading. It always exits 0.
• headroom hook install|uninstall|status --agent claude adds or removes one Claude Code UserPromptSubmit hook (a small shell script under ~/.headroom/hooks/) in CLAUDE_CONFIG_DIR or ~/.claude, plus ~/.claude2 when it exists. It backs each settings.json up once, leaves other hooks and keys alone, and refuses a file that does not parse. headroom setup offers it (default yes; --yes installs it only with --hook), headroom doctor reports its state as INFO, and headroom uninstall removes it. Not supported yet: Windows hook install, and Codex or Gemini hooks.

Fixed

• Model retirement requires three consecutive complete catalog reads without the model, including Claude and Codex. Failed, partial, loading and availability-only Antigravity reads cannot retire models. This fixes models flapping on and off in the model list.

v0.2.7

Documentation

• README: an agent-first opening, a "For agents" block to paste into CLAUDE.md or AGENTS.md, MCP registration out of the collapsed setup, and corrected claims about reservations, --allow-unknown, where secrets live, the Windows daemon pipe and process checks; docs/quickstart.md now describes the dashboard graph as the remaining-capacity burndown it draws.
• docs/concepts.md and the headroom skill: unused quota is information, not a target; leaving capacity unused at reset is acceptable (#131, thanks @terminalchai).

Fixed

• On a fresh home (no accounts.toml, or an empty one), status, can, gate, route and dashboard now print one clear "No accounts configured yet" message pointing at headroom accounts discover (or headroom setup) instead of a raw ENOENT. can, gate and route exit 2 (no capacity, never a yes); status (missing file) and dashboard exit 1; status with an empty file prints the message on stderr and keeps exit 0. The missing file is recognised by type, not by comparing path strings, which could miss on Windows (#142).
• An overlong Unix socket path now names the path, its UTF-8 byte length, the platform limit and the fix (a shorter HEADROOM_HOME) instead of a bare listen EINVAL. The daemon refuses to start with that message and headroom doctor reports it as a FAIL and continues its other checks; other commands still fall back to a direct read, with a one-line hint on stderr. Windows named pipes are unchanged (#105, #124, thanks @anshurajbisoyi98-ctrl).
• Windows: headroom uninstall --home no longer stops with "still running" or fails with EBUSY on headroom.db. schtasks /End never stopped the daemon, because it ends only the task's cmd.exe wrapper and not the node.exe it started. The daemon now takes an authenticated shutdown request over its named pipe (the same proof as every other mutating request; idempotent) and stops gracefully. headroom uninstall sends it, waits for the daemon to exit (the shared stop budget; callers wait 27 seconds, the daemon's own worst-case stop of 22 seconds plus a margin), ends the task as a backup, then removes the task and the home. If the daemon is still answering after the wait, uninstall keeps the home, prints instructions and exits 1; it never kills a process (#136).
• Windows: after an in-place upgrade, headroom install-service restarts a running daemon whose version or pipe name differs from the CLI's (shutdown request, wait, schtasks /Run, confirmed on the new pipe), instead of saying "already installed and running" and keeping the old one. headroom update restarts the service the same way. A daemon from 0.2.6 or earlier cannot take the request; install-service then says how to switch and leaves it serving on the older pipe name. health now reports the version the daemon started as.
• Windows: the daemon's named pipe is now \\.\pipe\headroom-<digest>, with no part of the username in the name. Clients fall back to the old name, so a daemon an older version started is still found until it restarts (#137).

Upgrade notes

• Windows: a daemon started by 0.2.6 or older must be stopped by hand once after upgrading (end node.exe), because it cannot be asked to shut down.

Documentation (Windows status)

• README and docs/quickstart.md: Windows verified status after a real Windows 11 retest of install-service, the hash-only pipe, uninstall and upgrade restart; what is still unverified is listed.

Internal

• CI runs a fast path for docs-only changes, type-checks the tests (lint:tests) and runs on push only for master; test fixes for pid races, an event-loop timing test and host guard launch timeouts (#126, #132, #133, #139, #144, #129, thanks @terminalchai).

v0.2.6

Changed

• Releases published as 0.2.5 read the Gemini CLI OAuth file for the Antigravity model list by default; 0.2.6 makes that opt-in.
• The Antigravity model-list check, which reads the Gemini CLI's OAuth file and calls Google's Code Assist fetchAvailableModels, is now off by default. Set antigravity_model_catalog = true in policy.toml to turn it back on. Antigravity quota is unaffected.

Documentation

• README: a not-affiliated notice, a "Vendor endpoints and your accounts" section listing each endpoint, credential and client header, Grok marked experimental, and exact wording for the Antigravity reader and the opt-out npm update check. SECURITY.md rules 5, 9 and 12 and THIRD_PARTY_NOTICES.md updated to match.