# AI use cases for Headroom (michellzappa/headroom) Repo: [michellzappa/headroom](https://github.com/michellzappa/headroom) | Use cases: 3 | Page: https://dedupedai.com/use-cases/michellzappa-headroom/ Headroom is a local-first macOS menu bar app that shows your AI coding quotas and CI, deploy, and monitor status, with optional iPhone, Watch, and ESP32 desk displays. This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL. - Check AI coding quota and ship status from the menu bar: https://dedupedai.com/use-cases/michellzappa-headroom/check-ai-quota-and-ship-status-from-menu-bar/ - Approve or deny coding agent requests from your iPhone: https://dedupedai.com/use-cases/michellzappa-headroom/approve-agent-requests-from-iphone/ - Read the local usage feed before starting a long agent task: https://dedupedai.com/use-cases/michellzappa-headroom/read-quota-feed-before-long-agent-run/ ## How to check AI coding quota and ship status from the menu bar with Headroom Repo: [michellzappa/headroom](https://github.com/michellzappa/headroom) | Difficulty: Beginner | Time: 15 minutes | Basis: From the README Install the Mac app to see remaining quota and failed CI or deploys without leaving your editor. **Who it is for:** A developer working in Claude, Codex, or Cursor on a Mac who keeps running into surprise usage limits and forgets to check whether CI or prod is healthy. **The problem:** Quota limits, failed Actions runs, and deploy problems are spread across billing pages, gh, and Vercel, so you break focus to check each one. **The outcome:** Thin quota tanks and an attention pip sit in the menu bar, and the popover shows Usage, Attention, and Activity from local data only. ### Steps 1. Download Headroom-macOS.zip from the Releases page on the Headroom GitHub repo and open Headroom.app. 2. Open the menu bar meters and follow the Welcome screen. 3. Confirm the detected providers, then select Continue. On a Release build the host starts automatically and stays up at login. 4. Run `curl -s localhost:8737/health | python3 -m json.tool` in Terminal to confirm the host is responding. 5. Open the popover and check the Attention tab for failed Actions runs, deploys, or monitors. ### Prompt to paste into your agent ```text Using the michellzappa/headroom repo, help me set up the Headroom macOS menu bar app for my account. Expected output: the menu bar shows quota tanks for the enabled providers, and the local health check returns JSON. Verify by running `curl -s localhost:8737/health | python3 -m json.tool` and confirming it responds. ``` ### Caveat The README says Headroom reads local state that other tools leave on your Mac and only works for providers already signed in on that machine. Risk, credentials: Headroom reads the auth and CLIs you already have on the Mac, so only install it on machines where you trust local access to those tool sessions. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/michellzappa-headroom/check-ai-quota-and-ship-status-from-menu-bar/ ## How to approve or deny coding agent requests from your iPhone with Headroom Repo: [michellzappa/headroom](https://github.com/michellzappa/headroom) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README Pair the iPhone app to your Mac so you can answer Claude or Codex requests when you are away from the desk. **Who it is for:** A developer whose Claude or Codex session is waiting on a yes or no while they are away from the desk, on the same LAN or Tailscale as their Mac. **The problem:** A coding agent pauses on an approval or question, and you only find out hours later when you return to your Mac. **The outcome:** Pending agent requests appear in the iPhone Attention tab, and you can approve, deny, or reply from the phone. Headroom answers the request but does not start new work. ### Steps 1. Install the Mac app and confirm the host is running with `curl -s localhost:8737/health | python3 -m json.tool`. 2. Install the iPhone app from TestFlight when it is published, or build it from source using docs/ios-companion.md. 3. In the Mac app, open Settings and copy the mobile token from iPhone pairing. Do not use the host token. 4. On the iPhone, pair with the Mac using the mobile token, then open the Attention tab. 5. Check the pending request, then approve, deny, or reply. Confirm the agent resumes on the Mac. ### Prompt to paste into your agent ```text Using the michellzappa/headroom repo, pair the Headroom iPhone companion with my Mac using the mobile token from Mac Settings. Expected output: a pending request appears in the iPhone Attention tab and can be answered. Verify by confirming the request is listed on the phone and the Mac host responds to `curl -s localhost:8737/health | python3 -m json.tool`. ``` ### Caveat The README says the iPhone companion needs the same LAN or Tailscale as the Mac and uses a mobile token, not the host token; it is not a cloud service. Risk, credentials: The iPhone is given access to approve or deny agent requests, so keep the mobile token private and do not use the host token on the phone. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/michellzappa-headroom/approve-agent-requests-from-iphone/ ## How to read the local usage feed before starting a long agent task with Headroom Repo: [michellzappa/headroom](https://github.com/michellzappa/headroom) | Difficulty: Advanced | Time: 45 minutes | Basis: From the README Query the local Headroom host for quota Headroom so an agent can decide whether a big task fits the remaining limit. **Who it is for:** A developer or script author who runs long coding agent jobs and wants a check on remaining quota before the job starts. **The problem:** A long agent run can hit a usage limit midway, wasting time and leaving work half done. **The outcome:** Your script or agent reads the local /usage JSON from the Headroom host and proceeds only if the remaining quota meets a threshold you set. ### Steps 1. Install and start the Mac app so the host runs on localhost:8737. 2. Confirm the host is up with `curl -s localhost:8737/health | python3 -m json.tool`. 3. Request the usage feed with `curl -s localhost:8737/usage | python3 -m json.tool` and read the provider windows. (inferred, check the README) 4. Compare the remaining session or weekly Headroom for your provider against your threshold in your script. (inferred, check the README) 5. Start the long agent task only when the check passes, and log the reading for later review. (inferred, check the README) ### Prompt to paste into your agent ```text Using the michellzappa/headroom repo, query the local Headroom host at localhost:8737 and read the /usage feed for . Expected output: a yes or no decision on whether remaining quota covers the task, based on a threshold of . Verify by confirming the /usage response parses as JSON before using it. ``` ### Caveat The README names the /usage feed and the localhost:8737 host, but does not document the response fields, so the threshold check must be written against the actual JSON your host returns. Risk, credentials: The usage feed reflects local tool sign-ins, so do not expose the host beyond your own machine or trusted LAN when scripts call it. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/michellzappa-headroom/read-quota-feed-before-long-agent-run/