Headroom 0.4.7

A small release that fixes iCloud sync setup in the iPhone and Apple Watch apps and makes downloading Headroom from the website more reliable. The Mac app itself is unchanged.

• iCloud sync fix for iPhone and Apple Watch. The companion apps now correctly read their iCloud sync configuration.
• Reliable download link. The Download button on headroom.taraxio.com now always points to the newest Mac release that has a finished installer. You won't hit a broken link while a new version is still uploading or if its build failed.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.4.6...v0.4.7

Headroom 0.4.6

This is a maintenance release with no changes to the Mac app; it refreshes the app icons for iPhone, iPad, and Apple Watch.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.4.5...v0.4.6

Headroom 0.4.5

A maintenance release that fixes the release build setup behind the scenes, with no changes to how Headroom works on your Mac.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.4.4...v0.4.5

Headroom 0.4.4

A maintenance release that consolidates the release process and versioning for the iOS apps; the Mac app itself is unchanged.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.4.3...v0.4.4

Headroom 0.4.3

A maintenance release that makes iCloud sync read your Mac's model more safely and prepares release signing and sync setup for the iPhone and Apple Watch apps.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.4.0...v0.4.3

Headroom 0.4.0

Headroom can now sync your usage over iCloud to Headroom on iPhone, iPad and Apple Watch.

• iCloud sync. A new Settings section lets your Mac publish your Claude and Codex usage to iCloud. Sync is off until you turn it on. The data is encrypted and stays within your Apple Account.
• Your plans on iPhone, iPad and Apple Watch. With sync on, Headroom on your other devices shows how each plan is pacing. You also get Home Screen widgets, Lock Screen and watch-face complications, and a Live Activity for your 5-hour session.
• One view per account across several Macs. Headroom now records which account email each plan belongs to. If you use the same account on more than one Mac, your other devices combine those Macs into a single view of that account.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.3.1...v0.4.0

Headroom 0.3.1

This release fixes the 5-hour session graph.

• The session graph shows this session. While a 5-hour session is running, the graph now runs from the session's start to its reset, so NOW sits where you actually are and the rest of the graph shows where you're heading. Before, it covered the whole last day, which put NOW near the end even with hours left. Between sessions, the graph still shows the last 24 hours.
• No more flat line and hooks. Earlier sessions could be drawn as a flat line along the top with small hooks at each reset. Each session now dips and refills where it really did.
• The session widget matches. The medium 5-Hour Session widget graphs the current session too, labelled "This session".

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.3.0...v0.3.1

Headroom 0.3.0

This release adds desktop widgets, so you can keep an eye on your limits without opening the menu bar.

• New desktop widgets. Right-click your desktop, choose Edit Widgets and search for Headroom. There are three:

  • Burn-o-meter (small, medium and large) is a speedometer for how fast you're spending your 5-hour session and your week, in percent per hour. The needle reads against the pace that lasts until the reset, and the widget shows how fast you can safely go. The large size adds your tokens and the API-rate cost for the last 24 hours.
  • Headroom (small, medium and large) shows what's left this week, where it's heading and when it renews. With two accounts signed in, the medium size shows both.
  • 5-Hour Session (small and medium) counts down to the reset, with a ring that shows what's left and a graph of the last day of sessions.

  Every widget gives the same forecast in the same words, like "70% left at the reset" or "Runs out 14:20". Click any widget to open Headroom.

• The session graph keeps the last 24 hours. In the popover, each 5-hour session dips as you use it and steps back up at its reset, so you can see how your day went.

• Earlier run-out warnings. When a heavy stretch of work would use up your week before it renews, Headroom now warns you from your recent usage instead of waiting for the daily average to catch up.

• An update dot in the menu bar. When an update is ready, a small blue dot appears on Headroom's icon, and the right-click menu offers to update and restart.

• Fan Control takes over more reliably. If macOS is slow to hand over the fans, Headroom now retries for a few seconds instead of failing.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.2.0...v0.3.0

Headroom Mobile 0.4.0

The first preview of Headroom on iPhone, iPad and Apple Watch, fed by your Macs over iCloud.

• Headroom for iPhone, iPad and Apple Watch. A new mobile app shows Now, account details, Activity and your Macs, with demo data to try it before syncing. It includes Home Screen widgets (including Accounts and Activity), Lock Screen and watch-face complications, a Live Activity for your 5-hour session, and a watchOS app.

• iCloud sync from your Mac. A new Settings section on the Mac, off by default, publishes your readings to iCloud. Data from every Mac you sync is merged into one view per provider account, and payloads are encrypted. Nothing leaves your Apple Account.

• See at a glance whether your week will last. Each provider gets a meter in the menu bar. The popover gives a plain verdict on whether you have room to spare, are on pace, or should slow down. It also shows a projection of where the week is heading and a history of past weeks.

• Warnings when recent use will run you out early. If you've been spending fast over the last couple of hours, Headroom warns you that you'll run out before the reset. Your daily pace stays available as extra context.

• First-class 5-hour sessions. Each session gets a forecast: how long it will last, how much you'll have spare at reset, or when it runs out. A meter and graph cover the running session from start to reset, and a 24-hour trail of recent sessions shows between them.

• Desktop widgets on the Mac. Three widgets are available:

  • Burn-o-meter: a speedometer of how fast you're spending, with a safe speed marked.
  • Headroom: what's left this week.
  • 5-Hour Session: a countdown ring for the current session.

  All three use the same forecast wording as the popover.

• Activity and cost breakdowns. See your token use by model, project and token class, with estimated costs. Models without a known price are flagged in a footnote rather than guessed.

• Welcome window and redesigned Settings. A short setup guide runs on first launch to pick providers and shape the menu bar. Settings now has sidebar sections with a live preview. You can configure:

  • The 5-hour warning level.
  • The menu bar percentage and an always-on session timer.
  • Appearance.
  • Notifications for nearing or hitting a limit, a session coming back, a tight week, and credits lapsing.

• Privacy-safe sharing. Copy a card image, a snapshot or text of your status. Shared content never includes project names, paths or session IDs.

• headroom in the terminal. Get a summary, JSON output, a status line for Claude, tmux, SketchyBar or plain text, and a wait command.

• Keep Awake. Keep your Mac from sleeping from the right-click menu. Choose a set time from 15 minutes to 8 hours, run indefinitely, or stay awake until your next session reset.

• Fan Control. Set a two-point fan curve from the right-click menu, with a choice of temperature sensor. Temperature and fan speed can be shown in the menu bar. Fan Control needs a helper approved in Login Items.

• Automatic updates. Headroom checks for updates daily and updates itself. A blue dot appears on the menu bar icon when an update is waiting.

• Easier to install. Headroom comes as a signed, notarized DMG and through Homebrew as ai-headroom, and it runs on macOS 15 Sequoia and later.

• Light on your Mac. The app idles at about 16–17 MB of memory and reads your usage logs locally. It only contacts Anthropic's usage API and the Claude and OpenAI status pages.

Install this pre-release:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash -s -- --version mobile-v0.4.0

Full changelog: https://github.com/ScaleXY/headroom/commits/mobile-v0.4.0

Headroom 0.2.0

This release adds Fan Control, so Headroom can run your Mac's fans on a simple temperature curve.

• New Fan Control. Right-click Headroom's menu bar icon and open Fan Control to set your fans with a two-point curve. Pick the sensor to follow (the CPU & GPU average by default, or CPU, GPU or the hottest core) and set a minimum and maximum temperature. The menu also shows the live reading. Below the minimum, macOS controls the fans as usual. As things heat up, the fans speed up at once and then slow down gently.
• Temperature and fan speed in the menu bar. While Fan Control is on, the menu bar shows the sensor temperature and fan speed. You can turn this off in Settings → Menu Bar.
• Fan Control picks up where you left off. Your curve, sensor choice and on/off setting are saved and resume the next time Headroom launches.
• Fan Control runs through a background helper. To turn it on, you approve Headroom's helper in Login Items, and the Fan Control menu takes you there. The helper only works with Headroom itself. It hands the fans back to macOS whenever Headroom stops using them, quits or crashes. If you installed with Homebrew, uninstalling Headroom removes the helper too.

Install or update:

curl -fsSL https://raw.githubusercontent.com/ScaleXY/headroom/main/install.sh | bash

Or with Homebrew: brew upgrade --cask ai-headroom.

Full changelog: v0.1.8...v0.2.0