{
 "schema_version": 1,
 "generated": "2026-10-31",
 "id": "michellzappa-headroom--read-quota-feed-before-long-agent-run",
 "repo": "michellzappa/headroom",
 "repo_url": "https://github.com/michellzappa/headroom",
 "repo_slug": "michellzappa-headroom",
 "title": "Read the local usage feed before starting a long agent task",
 "page_title": "How to read the local usage feed before starting a long agent task with Headroom",
 "summary": "Query the local Headroom host for quota Headroom so an agent can decide whether a big task fits the remaining limit.",
 "who": "A developer or script author who runs long coding agent jobs and wants a check on remaining quota before the job starts.",
 "problem": "A long agent run can hit a usage limit midway, wasting time and leaving work half done.",
 "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": [
  "Install and start the Mac app so the host runs on localhost:8737.",
  "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. (inferred, check the README)",
  "Compare the remaining session or weekly Headroom for your provider against your threshold in your script. (inferred, check the README)",
  "Start the long agent task only when the check passes, and log the reading for later review. (inferred, check the README)"
 ],
 "agent_prompt": "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.",
 "agents": [
  "any"
 ],
 "difficulty": "Advanced",
 "time": "45 minutes",
 "basis": "readme",
 "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.",
 "category": "Software and DevOps",
 "tags": [
  "Software and DevOps"
 ],
 "lang": "python",
 "requirements": [
  "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"
 ],
 "risk": "sensitive",
 "seen_in_the_wild": false,
 "mentioned_publicly": false,
 "risks": [
  {
   "tag": "credentials",
   "notice": "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."
  }
 ],
 "best": false,
 "score": 0.8,
 "evidence": [],
 "url": "https://dedupedai.com/use-cases/michellzappa-headroom/read-quota-feed-before-long-agent-run/",
 "md": "https://dedupedai.com/use-cases/michellzappa-headroom/read-quota-feed-before-long-agent-run/index.md",
 "disclaimer": "Deduped lists open-source repositories that belong to other people. We do not own, maintain, audit, or vouch for any of them, and a repo appearing here is not an endorsement or a safety check. The use cases, steps, and prompts are written by AI and may be incomplete, outdated, or just wrong. Where a use case is marked \"Seen in the wild\", we link to public posts where someone described something similar, but we have not verified those posts and the use case itself is still our AI's own write-up. Use all of this at your own risk. Only run code, commands, or agents on systems and accounts you are authorized to use, and read the code and every command before you run it, especially anything that touches credentials, files, or the network. Nothing here is professional, security, legal, or financial advice. All trademarks and project names belong to their respective owners, and their use here does not imply affiliation. Content is provided as is, without warranties of any kind. Found a mistake, a safety problem, or something you want removed? Email hello@dedupedai.com and we will look at it promptly.",
 "api": "https://dedupedai.com/api/v1/usecases/michellzappa-headroom--read-quota-feed-before-long-agent-run.json",
 "api_version": "v1"
}