claudeers.
// Productivity

headroom

macOS menu bar stats with live graphs: CPU, GPU, memory, battery, plus Claude Code and Grok plan limits and token usage.

// Productivity[ cli ][ api ][ claude ]#claude#productivity◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
100/100
last commit 22 days ago
last release 22 days ago
releases 6
open issues 0
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up headroom (release-binary project) into my current project.
Found on https://claudeers.com/headroom-4
Repo: https://github.com/sandrich/headroom
Homepage/docs: —
Detected install method: release-binary → inspect the README
Category: productivity. Platforms: cli, api.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/sandrich/headroom/releases
// or clone
git clone https://github.com/sandrich/headroom

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageSwift

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Headroom

Headroom

A tiny macOS menu bar app that shows how much headroom you have left: on your machine (CPU, GPU, memory, battery) and on your AI coding plans (Claude Code and Grok).

One compact, native-looking item in the menu bar. Click it for a dashboard with live graphs; hover an item to see what is using it.

Headroom menu bar item and dashboard

Features

Menu bar

  • One line, monochrome, tinted by macOS like every other menu bar item
  • CPU and GPU with live sparklines, memory, battery
  • Claude Code limits as three slim gauges (5h session, weekly, per-model weekly such as Fable)
  • Grok credits gauge
  • Each item can be switched on or off; sampling every 0.5 to 5 seconds

Hover

  • CPU, GPU, memory, battery: top apps (helper processes are grouped under their app)
  • Claude, Grok: exact limit percentages and reset times

Dashboard

  • Live charts for CPU (with per-core bars), GPU and memory; battery state, power draw, health and cycles
  • Claude Code plan limits with reset countdowns and a pace marker (where you would be if usage were spread evenly)
  • Grok weekly credits
  • Combined token usage for Claude Code and Grok: today, last 7 days, last 30 days, tokens and cost, a 30-day chart by model family, and a per-model table, similar to ccusage

Providers you do not use are hidden automatically.

Keep awake (like Amphetamine or caffeinate)

  • Keep the Mac from idle sleeping for 1, 2, 4 or 8 hours, or indefinitely, from the cup menu in the dashboard footer
  • Option-click the menu bar item to toggle it; a cup appears in the menu bar while it is on
  • Optional: stay awake while Claude Code or Grok is working (any transcript written in the last 10 minutes), so long agent runs are not cut off by sleep
  • Optionally keep the display on too
  • Uses a standard power assertion (visible in pmset -g assertions), released automatically if Headroom quits; closing the lid still sleeps

Requirements

  • macOS 14 or newer (built and tested on Apple Silicon)
  • Xcode command line tools (Swift 5.9+)
  • Optional: Claude Code signed in with a Claude subscription
  • Optional: the Grok CLI signed in (grok login)

Install

  1. Download the latest Headroom-x.y.dmg from Releases.
  2. Open it and drag Headroom onto Applications.
  3. Launch Headroom. It lives in the menu bar, not the Dock.

Headroom is not notarized by Apple yet, so macOS blocks the first launch once. Open System Settings > Privacy & Security and click Open Anyway, or run xattr -dr com.apple.quarantine /Applications/Headroom.app.

Build from source

./build.sh            # builds build/Headroom.app
./build.sh install    # copies it to /Applications and launches it
./build.sh dmg        # packages build/Headroom-<version>.dmg

Builds are universal (Apple Silicon and Intel). To publish a release, bump CFBundleShortVersionString in Resources/Info.plist, then push a matching tag such as v1.1; the release workflow builds the DMG and attaches it.

Headroom registers itself as a login item on first launch. Turn that off under Settings in the dashboard footer.

How it works

Everything is sampled locally and cheaply. Steady-state cost is around 1% of one core with the dashboard closed.

DataSource
CPUhost_processor_info tick deltas
Memoryhost_statistics64 (app + wired + compressed, like Activity Monitor), memory pressure via sysctl
GPUIOKit IOAccelerator PerformanceStatistics
BatteryIOKit power sources and AppleSmartBattery
Top appslibproc (proc_pid_rusage) and per-client GPU time from the GPU driver's IORegistry entries; only sampled while a hover panel is open
Claude Code limitsThe usage endpoint Claude Code itself uses, authenticated with Claude Code's OAuth token from the login keychain (read via /usr/bin/security; never stored, logged or refreshed by Headroom)
Claude Code tokens~/.claude/projects/**/*.jsonl, tailed incrementally by byte offset and cached in ~/Library/Application Support/Headroom
Grok creditsThe billing endpoint the Grok CLI's /usage uses, with the CLI's token from ~/.grok/auth.json. If that token has expired, Headroom runs grok models once so the CLI refreshes it; Headroom never writes the file.
Grok tokens~/.grok/sessions/*/*/usage.json
PricesLiteLLM's model price list, refreshed daily

Accuracy notes

  • Token totals follow ccusage's rules: deduplicated by message id and request id, keeping the final counts of messages that were logged several times while streaming, and including advisor sub-calls. Days are local calendar days; "7 days" and "30 days" include today.
  • Cost can differ slightly from ccusage because Headroom prices 1-hour cache writes at their own (higher) rate.
  • Grok cost comes from the CLI's own per-turn cost figures.
  • Energy in the battery hover panel is shown as each app's share of energy used, because the kernel counters do not have a documented unit.
  • Root-owned processes (for example WindowServer CPU or kernel_task) cannot be read without elevated rights and are missing from the CPU, memory and energy lists.

Caveats

The Claude and Grok usage endpoints are not public APIs. They may change without notice, in which case those sections show the last known values and an error until Headroom is updated.

Development

swift build                                     # debug build
swift test                                      # unit tests (Swift Testing)
.build/release/Headroom --snapshot /tmp/shots   # renders the menu bar strip and dashboard to PNGs, then exits

Source layout (Sources/Headroom):

  • main.swift: app delegate, timers, status item, popover
  • SystemSampler.swift: CPU, GPU, memory, battery
  • Consumers.swift: per-app top consumers for the hover panels
  • Clients.swift: Claude Code and Grok plan limits
  • Ledger.swift: token ledger, pricing, summaries
  • StatusRenderer.swift: draws the menu bar strip
  • PopoverView.swift, Hover.swift: SwiftUI dashboard and hover panels
  • KeepAwake.swift: keep awake power assertion

scripts/make-icon.swift regenerates Resources/AppIcon.icns, scripts/make-banner.swift regenerates docs/banner.png.

Tests live in Tests/HeadroomTests and run on every push and pull request.

License

MIT, see LICENSE.

// faq

What is headroom?

macOS menu bar stats with live graphs: CPU, GPU, memory, battery, plus Claude Code and Grok plan limits and token usage.. It is open-source on GitHub.

Is headroom free to use?

headroom is open-source under the MIT license, so it is free to use.

What category does headroom belong to?

headroom is listed under productivity in the Claudeers registry of Claude-compatible tools.

8 views
★ 26 stars
unclaimed
updated about 1 month ago

// embed badge

headroom on Claudeers
[![Claudeers](https://claudeers.com/api/badge/headroom-4.svg)](https://claudeers.com/headroom-4)

// retro hit counter

headroom hit counter
[![Hits](https://claudeers.com/api/counter/headroom-4.svg)](https://claudeers.com/headroom-4)

// reviews

// guestbook

0/500

// related in Productivity

🔓

Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.

// productivitykepano/★ 52,609◷ MIT[ claude ]
🔓

Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork

// productivityanthropics/⟨Python⟩★ 34,871◷ Apache-2.0[ claude ]
🔓

Garry's Opinionated OpenClaw/Hermes Agent Brain

// productivitygarrytan/⟨TypeScript⟩★ 33,099◷ MIT[ claude ]
🔓

An open-source alternative to Claude Cowork (powered by opencode)

// productivitydifferent-ai/⟨TypeScript⟩★ 24,523◷ NOASSERTION[ claude ]
→ see how headroom connects across the ecosystem