DEDUPED Hot AI repos. Real use cases. What people build. Get the Monday 5

How to read the local usage feed before starting a long agent task with Headroom

Query the local Headroom host for quota Headroom so an agent can decide whether a big task fits the remaining limit.

Short answer: Install and start the Mac app so the host runs on localhost:8737; then Confirm the host is up with curl -s localhost:8737/health | python3 -m json.tool; Request the usage feed with curl -s localhost:8737/usage | python3 -m json.tool and read the provider windows. All steps.

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.

Who it is forA developer or script author who runs long coding agent jobs and wants a check on remaining quota before the job starts.

The problemA long agent run can hit a usage limit midway, wasting time and leaving work half done.

The outcomeYour script or agent reads the local /usage JSON from the Headroom host and proceeds only if the remaining quota meets a threshold you set.

What you need first

  • macOS 14 or later for the menu bar app
  • Python 3.9 or later (the bundled host is stdlib only, using /usr/bin/python3)
  • At least one AI coding tool already signed in locally
  • Optional: iPhone or iPad on iOS 17 or later, on the same LAN or Tailscale as the Mac
  • Optional: PlatformIO and a Waveshare ESP32-S3-Touch-AMOLED-1.8 for the desk board

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 for your agent

Using the michellzappa/headroom repo, query the local Headroom host at localhost:8737 and read the /usage feed for <provider name>. Expected output: a yes or no decision on whether remaining quota covers the task, based on a threshold of <threshold>. 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.

Use this in your AI agent

Ask your agent

Using the Deduped MCP, get the setup steps for michellzappa/headroom and "Read the local usage feed before starting a long agent task"

Add Deduped to Claude Code once

claude mcp add --transport http deduped https://dedupedai.com/mcp

Cursor, ChatGPT, others

Share: X LinkedIn Hacker News Email Copy link

Third-party repos we don't own. AI-written use cases can be wrong. Disclaimer