Development
Plugin
headroom
**Your AI coding quotas and ship status — in the menu bar, on your phone, and optionally on the desk.** When you're deep in Claude, Codex, or Cursor, you shouldn't have to dig through billing pages, gh, and Vercel to answer: *Am I about to hit a limit?
Plugin Signal62/100Solid
maintained100
capable14
documented75
adopted51
What's inside
README
1Headroom
Your AI coding quotas and ship status — in the menu bar, on your phone, and optionally on the desk.
When you're deep in Claude, Codex, or Cursor, you shouldn't have to dig through
billing pages, gh, and Vercel to answer: Am I about to hit a limit? Did CI
go red? Is prod healthy?
Headroom is a local-first macOS menu bar app (+ optional iPhone / Watch). One Python host on your Mac reads the auth and CLIs you already have and serves a single JSON feed. No Headroom cloud account — tokens stay on the machine.
| Surface | What you see |
|---|---|
| Menu bar | Thin remaining-quota tanks for the first three enabled providers + amber/red attention pip |
| Popover | Usage (rings, daily burn, spend), Attention, Activity (Recent feed + service panels) |
| Notification Center | Same widget as the iPhone: rings small, combined burndown medium |
| iPhone / iPad | Same three tabs — Usage, Attention, Activity — plus Settings, notifications, widgets |
| Apple Watch | Two complications: rings, or the week's burndown |
| ESP32 desk board (optional) | Same three rings + burndown on a Waveshare AMOLED — docs/esp32.md |
~/.claude / ~/.codex / Cursor / … Mac (Python, stdlib) Clients
Vercel · git · gh · SB · … ──▶│ headroom_server.py :8737 │◀── menu bar
~/.headroom/{config,sources} │ + usb_bridge │◀── iPhone
└──────────────────────────┘◀── ESP32 (opt.)
Why it exists
- Quota anxiety — session / weekly windows, pace, and spend on one ring (and a menu-bar tick per provider in focus).
- Ship status ambient — failed Actions, deploys, and monitors as an Attention pip and queue, not another tab.
- Agents away from the desk — approve, deny, or reply to Claude / Codex requests from Attention on iPhone (Headroom answers; it does not start work).
- Local-first — credentials and CLIs you already have; optional board can fall back to USB when hotel Wi‑Fi blocks mDNS.
Requirements
| Need | Notes |
|---|---|
| macOS 14+ | Menu bar app |
| Python 3.9+ | Bundled host is stdlib only (system /usr/bin/python3) |
| At least one AI coding tool | Already signed in locally |
| Optional: iPhone / iPad (iOS 17+) | Same LAN or Tailscale as the Mac |
| Optional: PlatformIO | Only to flash the desk board |
No Headroom cloud account.
Quick start
1. Mac app (Release)
- Download Headroom-macOS.zip from Releases.
- Open
Headroom.app→ menu bar meters → Welcome. - On a Release build the host starts automatically and stays up at login.
- Confirm detected providers → Continue.
Build from source, Xcode, and signing: macos/README.md.
2. iPhone (optional)
TestFlight when published, or build from source — docs/ios-companion.md. Use the mobile token from Mac Settings → iPhone pairing (not the host token).
3. Desk board (optional)
Waveshare ESP32-S3-Touch-AMOLED-1.8 only. Flash, config, brightness: docs/esp32.md.
After install
| Topic | Doc |
|---|---|
| Providers, accounts, Integrations, colours, focus, tokens | docs/setup.md |
~/.headroom keys + HTTP endpoints | docs/host.md |
| Something’s broken | docs/troubleshooting.md |
curl -s localhost:8737/health | python3 -m json.tool
Docs
| Doc | For |
|---|---|
| macos/README.md | Menu bar — build, Xcode, signing |
| docs/setup.md | First run, Providers, Integrations, tokens |
| docs/host.md | Config files + API surface |
| docs/ios-companion.md | iPhone pairing + widgets |
| docs/watch.md | Apple Watch complications |
| docs/esp32.md | Optional Waveshare desk display |
| docs/troubleshooting.md | Symptom → fix |
| docs/glossary.md | Shared chrome names |
| docs/rings.md | Ring / pace semantics |
| docs/contract.md | Changing /usage safely |
| docs/trust.md | Who may call which routes |
| docs/product.md | Standing product decisions |
| docs/metering.md | Meter kinds |
| docs/attention.md | Attention rollup policy |
| docs/agent-attention.md | Coding-agent gateway |
| docs/multi-mac.md | CloudKit settings sync |
| docs/telemetry.md | Anonymous product diagnostics |
| docs/updater.md | In-app update feed |
| docs/releasing.md | Notarize, TestFlight, cut-release |
| docs/appstore.md | App Store listing + screenshots |
| docs/privacy.md | Privacy policy |
| docs/install-links.md | Release + TestFlight URLs |
| docs/backlog.md | What’s queued |
| CHANGELOG.md | Per-version notes |
| CONTRIBUTING.md | Build, test, PR expectations |
| SECURITY.md | Threat model + reporting |
Contributing
Build and test commands: CONTRIBUTING.md. The host is
stdlib-only Python; every surface has to keep agreeing about /usage.
Security reports go through SECURITY.md.
License
MIT — see LICENSE.
Headroom reads local state that other tools leave on your Mac. It is not affiliated with, endorsed by, or supported by Anthropic, OpenAI, Anysphere, GitHub, Google, JetBrains, Zed, Codeium, Vercel, Supabase, Plausible, PostHog, Sentry, Datadog, or Axiom. Those names appear here to say what is being measured.
File tree
397michellzappa/headroomView on GitHub
.claude/
commands/
cleanup.md
.github/
workflows/
ci.yml
release.yml
.gitignore
AGENTS.md
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
docs/
.nojekyll
agent-attention.md
appstore/
appstore.md
icon-1024.png
screenshots/
01-overview.png
02-attention.png
03-activity.png
attention.md
backlog.md
CNAME
contract.md
demo_usage.json
esp32.md
glossary.md
host-merge.md
host.md
install-links.md
ios-companion.md
latest.json
meet/
latest.json
metering.md
multi-mac.md
orgs.md
privacy.md
product.md
releasing.md
rings.md
screenshots/
esp32-glance.png
ios-activity.png
ios-attention.png
ios-overview.png
macos-menubar-icon.png
macos-menubar.png
macos-popover.png
setup.md
telemetry.md
troubleshooting.md
trust.md
updater.md
watch.md
firmware/
platformio.ini
src/
boot_max.h
config_example.h
main.cpp
pin_config.h
provider_marks.h
version.py
host/
accounts.py
activity_history.py
agent_events.py
agent_gateway.py
agent_request.py
ai_gateway_usage.py
app_config.py
auth.py
axiom_monitors.py
balance_spend.py
burndown.py
cache_util.py
claude_code.py
claude_history.py
claude_hooks.py
claude_status.py
codex_app_server.py
codex_resets.py
codex_usage.py
com.centaur-labs.headroom.plist
config.example.json
copilot_usage.py
cursor_usage.py
daily_burn.py
datadog_monitors.py
detect_sources.py
device_view.py
gemini_usage.py
git_activity.py
github_actions.py
grok_usage.py
headroom_server.py
host_version.py
http_util.py
icloud_sync.py
jetbrains_usage.py
keychain.py
local_servers.py
machine_identity.py
meters.py
oauth_usage.py
openrouter_usage.py
parent_watch.py
plausible_usage.py
posthog_usage.py
pricing.py
quota_samples.py
quota_util.py
quota.py
sentry_alerts.py
shared_prefs.py
sources_config.py
supabase_usage.py
test_accounts.py
test_activity_history.py
test_activity.py
test_agent_events.py
test_agent_http.py
test_agent_request.py
test_alert_sources.py
test_app_config.py
test_auth.py
test_balance_meters.py
test_burn_priors.py
test_burndown.py
test_cache_util.py
test_claude_code.py
test_claude_history.py
test_claude_hooks.py
test_claude_status.py
test_codex_app_server.py
test_codex_resets.py
test_contract.py
test_cursor_usage.py
test_daily_burn.py
test_detect_sources.py
test_github_actions.py
test_host_version.py
test_icloud_sync.py
test_keychain_prompts.py
test_local_servers.py
test_mobile_controls.py
test_new_quota_providers.py
test_oauth_refresh.py
test_parent_watch.py
test_plausible_usage.py
test_posthog_usage.py
test_quota_registry.py
test_quota_samples.py
test_request_origin.py
test_service_pickers.py
test_services_order.py
test_stale_quota.py
test_supabase_usage.py
test_usb_bridge.py
test_xcode_builds.py
usb_bridge.py
vercel_builds.py
VERSION
windsurf_usage.py
xcode_builds.py
zed_usage.py
ios/
ExportOptions.plist
HeadroomMobile/
ActivityScreen.swift
Assets.xcassets/
AboutAppIcon.imageset/
AboutAppIcon.png
Contents.json
AccentColor.colorset/
Contents.json
AppIcon.appiconset/
Contents.json
HeadroomIcon.png
Contents.json
AttentionScreen.swift
BonjourDiscovery.swift
HeadroomMobile.entitlements
HeadroomMobileApp.swift
Info.plist
MobileAgentAttentionArchive.swift
MobileBackgroundRefresh.swift
MobileConnection.swift
MobileNotifications.swift
MobileSettingsScreen.swift
MobileSnapshotArchive.swift
MobileUsageStore.swift
PageEmptyState.swift
PairingView.swift
QuotaViews.swift
RootView.swift
ServiceSections.swift
WatchBridge.swift
WidePhoneLayout.swift
HeadroomMobileTests/
MobileContractTests.swift
LICENSE
macos/
Assets.xcassets/
AboutAppIcon.imageset/
AboutAppIcon.png
Contents.json
AppIcon.appiconset/
Contents.json
icon_128x128.png
icon_128x128@2x.png
icon_16x16.png
icon_16x16@2x.png
icon_256x256.png
icon_256x256@2x.png
icon_32x32.png
icon_32x32@2x.png
icon_512x512.png
icon_512x512@2x.png
Contents.json
ESP32Glance.imageset/
Contents.json
esp32-glance.png
Headroom-CloudKit.ckdb
Headroom-iCloud.entitlements
Headroom.entitlements
project.yml
README.md
Sources/
AccentPicker.swift
ActivitySection.swift
BalanceSpendSection.swift
BuildsSection.swift
BurndownCard.swift
CodexBarProgressBar.swift
DailyBurnCard.swift
DashboardChrome.swift
DashboardView.swift
HeadroomApp.swift
HeadroomClient.swift
HostController.swift
HostLifecycle.swift
HostVersion.swift
Keychain.swift
LaunchAtLogin.swift
MachineCloudSync.swift
MachinesSection.swift
PlausibleSection.swift
PostHogSection.swift
QuotaSection.swift
ResetNotifications.swift
ServersSection.swift
ServiceDetailSelection.swift
Settings/
SettingsSourceRow.swift
SettingsSourcesPane.swift
SettingsView.swift
SettingsView+AlertSources.swift
SettingsView+CodingAgents.swift
SettingsView+General.swift
SettingsView+Git.swift
SettingsView+GitHub.swift
SettingsView+Helpers.swift
SettingsView+Integrations.swift
SettingsView+iPhone.swift
SettingsView+OpenRouterAIGateway.swift
SettingsView+OtherMacs.swift
SettingsView+Plausible.swift
SettingsView+PostHog.swift
SettingsView+Sources.swift
SettingsView+Supabase.swift
SettingsView+Telemetry.swift
SettingsView+Vercel.swift
SettingsWindowConfigurator.swift
SetupView.swift
SpendCard.swift
StatusItemController.swift
SupabaseSection.swift
Telemetry.swift
UpdateCheck.swift
UsageStore.swift
WelcomeGlass.swift
WelcomeView.swift
WelcomeWindow.swift
Tests/
ChangelogTests.swift
ContractTests.swift
HostLifecycleTests.swift
HostVersionTests.swift
MenuBarIconStyleTests.swift
ModelsTests.swift
UpdateCheckTests.swift
THIRD_PARTY_NOTICES.md
README.md
scripts/
build-app.sh
build-ios.sh
changelog-section.sh
check-glossary-copy.sh
check-mirrored-constants.sh
compose_menubar_preview.py
cut-release.sh
flash-esp32.sh
frame_appstore_screenshots.py
gen-project.sh
generate_screenshots.sh
gfx_font.py
install-host.sh
ios_manual_sign_pbxproj.py
render_esp32_boot.py
render_esp32_preview.py
render_icon.py
setup-release-secrets.sh
ship-inventory.sh
ship-ios.sh
sync-embedded-host.sh
testflight-url.sh
uninstall-host.sh
update-app.sh
version-env.sh
write-update-feed.sh
SECURITY.md
Shared/
AboutHeadroomView.swift
ActivityFeedRow.swift
ActivityHistoryHeatmap.swift
ActivityStatus.swift
AgentRequestView.swift
AttentionList.swift
BalanceSpendCard.swift
BurndownChartCanvas.swift
BurndownChartMath.swift
Changelog.swift
ChangelogView.swift
DrainedColor.swift
FlowingActions.swift
HeadroomCopy.swift
HeadroomFormat.swift
HeadroomModels.swift
HeadroomPalette.swift
HeadroomRings.swift
HealthModels.swift
IntegrationWatch.swift
LossyDecode.swift
MenuBarIconStyle.swift
PermalinkButton.swift
PlausibleTrafficChart.swift
ProviderIcon.swift
ProviderIcons.xcassets/
Contents.json
ProviderAIGateway.imageset/
Contents.json
ProviderAIGateway.svg
ProviderClaude.imageset/
Contents.json
ProviderClaude.svg
ProviderCodex.imageset/
Contents.json
ProviderCodex.svg
ProviderCopilot.imageset/
Contents.json
ProviderCopilot.svg
ProviderCursor.imageset/
Contents.json
ProviderCursor.svg
ProviderGemini.imageset/
Contents.json
ProviderGemini.svg
ProviderGit.imageset/
Contents.json
ProviderGit.svg
ProviderGitHub.imageset/
Contents.json
ProviderGitHub.svg
ProviderJetBrains.imageset/
Contents.json
ProviderJetBrains.svg
ProviderOpenRouter.imageset/
Contents.json
ProviderOpenRouter.svg
ProviderPlausible.imageset/
Contents.json
ProviderPlausible.svg
ProviderPostHog.imageset/
Contents.json
ProviderPostHog.svg
ProviderSupabase.imageset/
Contents.json
ProviderSupabase.svg
ProviderVercel.imageset/
Contents.json
ProviderVercel.svg
ProviderWindsurf.imageset/
Contents.json
ProviderWindsurf.svg
ProviderZed.imageset/
Contents.json
... 56 moreFAQ
headroom is a Claude Code plugin with hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is headroom?
- **Your AI coding quotas and ship status — in the menu bar, on your phone, and optionally on the desk.** When you're deep in Claude, Codex, or Cursor, you shouldn't have to dig through billing pages, gh, and Vercel to answer: *Am I about to hit a limit?
- How do I install headroom?
- Run these in Claude Code: . Then prompt normally.
- Does headroom auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is headroom free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.