A fuel gauge for AI agents

My car plans its own charging stops. My AI agents could not even tell whether they had enough left to finish a job. Notes on Headroom, the gauge I built so they can check before they start.

By 6 min readBuildingAI & work

Generative contour artwork.

Listen to this note

6 minutes · two hosts talk it through

0:00Intro6:05
Chapters
Transcript

AlexThis is the audio version of a Field Notes piece by Martijn Hermans, about Headroom, a fuel gauge for his AI agents.

SamI'm Sam.

AlexAnd I'm Alex. We're both synthetic voices. The script was written by an AI from Martijn's article, and voiced with PodcastD, the podcast tool he builds himself.

SamIt starts on the road trip to the Arctic. The plan: the agents keep working on his projects, and he spends the days with his family.

AlexChecking their work was the part he had signed up for. Babysitting their limits was not. A plan would hit a cap halfway, another account still had room, and somebody had to pick which model took over. That kept pulling him back to a screen.

SamMeanwhile, the Tesla plans its own charging stops. He doesn't watch the gauge.

AlexThe agents could already write the code, and even test the software through computer use. What they could not tell him was whether they had enough allowance left to finish.

SamSo before an agent starts a job, Headroom checks whether the estimated demand fits the remaining allowance and the reserves he has set, and gives an answer the agent can act on.

AlexThe article shows an example terminal, with synthetic data. A Claude account with plenty of room. A Codex account at eighty-one percent of its week. Then an agent asks whether it can start a Codex build, and the answer is no.

SamThere is still allowance left, but usage is ahead of the pace set for this week, so under the default pacing rule it's kept for later.

AlexAnd he says the parts worth telling are the ones he got wrong first.

SamFirst, treating usage as one number.

AlexThe usage screens say what he's used, not whether the next job fits. An account can have a short window and a weekly one. A model can have its own allowance on top of the account limit. A job may draw on both, and room in one does nothing if the other is empty.

SamSo Headroom models an account as a set of meters with windows, and every reading says which window, when it was taken and when it resets. If any window doesn't fit, or a reading is unknown, the answer is wait.

AlexModel choice stays out of the tool. His routing file says which models he'll use for what, and Headroom only checks which of those fit.

SamNext, two agents look at the same account a moment apart. Both see room, both start, and together they overshoot.

AlexSo when an agent starts work through headroom run, or asks for a lease, Headroom checks and reserves capacity in one operation, under one write lock, so the second agent sees the first one's claim.

SamIn the article's simplified example, the first job reserves twelve points. When the second asks, only three are free, so it's refused.

AlexWith headroom run, the lease is released when the command exits. A lease taken directly must be released, or it expires.

SamAnd he's straight about what it is.

AlexA promise between agents that bother to ask. It doesn't throttle a model or stop a job at its estimate, and does nothing about a tool that ignores Headroom. The vendor still holds the real limit.

SamThen his own rules got in the way.

AlexHe had set aside part of an allowance. Later a reset was available and work was queued, but the reserve was still in the config. Two sessions ran into it before he understood why.

SamNow reserves carry a reason, a date and an expiry, and when Headroom says no, it points at the rule. Which beats arguing with a red light.

AlexThere's also a mode for finishing a real queue before a reset. It still respects the caps. He doesn't want agents inventing work to empty a meter. Unused allowance is information, not a target.

SamAll of that assumes he's looking. But the car also tells you when something changes.

AlexSo Headroom can message his phone about things he'd notice too late. A weekly window that resets early and unannounced, a free reset credit, a source that stops answering, a threshold crossed. The point is finding out while there's still time to use it.

SamThrough Telegram, ntfy or a webhook, and only once you pick a channel. A reset can need a second vendor reading first, and the same event is sent at most once every six hours, because a nudge you learn to ignore is worse than none.

AlexThe agents don't replan after a reset yet. The notifications come to him. Automatic replanning is what he wants to explore next.

SamWhere does it stand?

AlexHeadroom reads some undocumented vendor endpoints. His tests cover the responses he's seen, but those can change. Estimates come from recent burn and similar finished jobs, with a sample count and no promise. A dependable conversion from tokens to subscription quota is future work.

SamWithin those limits, it does the job he built it for. It's for anyone running more than one agent or subscription who'd rather not watch the meters, especially when work runs unattended.

AlexTo try it, install it and run headroom setup once. Then headroom shows your meters, and headroom can asks whether a job fits. A demo with synthetic data needs no logins.

SamIt's MIT licensed and works with any agent that can run shell commands. macOS is the main platform, and Claude Code is the tested MCP client.

AlexIf you try it, he'd like to hear what's missing, or where it gets a decision wrong. The full piece is on Field Notes, and Headroom is on GitHub.

SamThanks for listening.

Made with PodcastD, the in-house tool I build for turning writing into podcasts. Claude wrote the script from this note; the voices are synthetic (Kokoro (am_michael, af_sarah)) and everything was rendered on my own machine.

The plan for the road trip was simple: the agents keep working on my projects, and I spend the days with my family. Prompting them and checking their work was the part I had signed up for. Babysitting their limits was not. A plan would hit a cap halfway, another account still had room, and somebody had to work out which model could take over. That is what kept pulling me back to a screen.

The car was doing the opposite. When I put a destination into the Tesla, it plans its own charging stops. I don’t watch the gauge. I say where I’m going and it works out what the battery needs to get there.

So why can’t an agent do that? The agents could already write the code, and even test the software through computer use. What they could not tell me was whether they had enough allowance left to finish.

Headroom is my attempt at the missing piece. It’s a small tool on my own machine. Before an agent starts a job, it checks whether the estimated demand fits the remaining allowance and the reserves I’ve set. It gets an answer it can act on. This is what it shows:

Illustrative example · synthetic data

$ headroom
claude-main  claude  Max 20x  fresh <1m
  all      5h  [█░░░░░░░░░]  11% used  resets in 3h 14m  HARVEST
           wk  [░░░░░░░░░░]   3% used  resets in 5d 14h  HARVEST

codex-main  codex  Plus  fresh <1m
  credits  1 available, expire Oct 15
  main     wk  [████████░░]  81% used  resets in 5d 14h  CONSERVE

gpu-box  UP  local-27b  0 running, 0 waiting

3 principals, daemon fresh <1m ago

$ headroom can codex-build
NO codex-main:main CONSERVE (wk 81% CONSERVE)
What Headroom prints: the status view, then a check that says no because the Codex week is ahead of pace.

The Codex check says no at 81% used. There is still allowance left, but usage is ahead of the pace set for this week. Under Headroom’s default pacing rule, that remaining capacity is kept for later.

The parts worth telling are the ones I got wrong first.

A percentage is not an answer

The usage screens tell me what I’ve used. They don’t tell my agents whether the next job fits. A single percentage is a poor answer to “can this job start?” An account can have a short window and a weekly one. A model can have its own allowance on top of the account-wide limit. A job may draw on both, and room in one does nothing for you if the other is empty. So Headroom models an account as a set of meters, each with windows, and a reading says which window it belongs to, when it was taken and when it resets.

I also keep model choice out of the tool. My routing file says which models I’m willing to use for what, and Headroom only checks which of those fit. An independent review shouldn’t go back to the model family that wrote the change just because that account has the most room.

Can this job start?

Not yet. Two windows have room and one does not, and spare room elsewhere does not make up for it.

Can this job start? One decision across three windowsIllustrative example with synthetic data. A job expects to use about 12 points of each window it draws from. It draws from three windows, each shown as a bar of 100 points. All models, 5-hour window: 38 used, 10 reserved by other jobs, 10 kept in reserve, 42 free, so it fits. All models, weekly window: 71 used, 15 reserved by other jobs, 10 kept in reserve, 4 free, so it does not fit. Model B only, weekly window: 30 used, none reserved by others, 10 kept in reserve, 60 free, so it fits. The decision is wait: one window is short, and room in the other two does not help.Illustrative example · synthetic dataThe job: a code review that expects to use about 12 points of every window it draws from. It draws on the account-wide windows and onModel B's own allowance.WindowCan the job fit?All models5-hour window1238 used, 10 reserved by other jobs, 10 kept in reserve, 42 free. Read 2 min ago.Fits42 freeAll modelsWeekly windowneeds 1271 used, 15 reserved by other jobs, 10 kept in reserve, 4 free. Read 2 min ago.Does not fit4 free, needs 12Model B onlyWeekly window1230 used, 0 reserved by other jobs, 10 kept in reserve, 60 free. Read 3 min ago.Fits60 freeusedreserved by other jobskept in reservefreethis job's 12Decision: WAITThe weekly window of All models has 4 points free and the job needs 12. Room in the other two windows does not help. The agent triesanother model family from its list, or waits for a reset and asks again.
Can this job start? One decision across three windowsIllustrative example with synthetic data. A job expects to use about 12 points of each window it draws from. It draws from three windows, each shown as a bar of 100 points. All models, 5-hour window: 38 used, 10 reserved by other jobs, 10 kept in reserve, 42 free, so it fits. All models, weekly window: 71 used, 15 reserved by other jobs, 10 kept in reserve, 4 free, so it does not fit. Model B only, weekly window: 30 used, none reserved by others, 10 kept in reserve, 60 free, so it fits. The decision is wait: one window is short, and room in the other two does not help.Illustrative example · synthetic dataThe job: a code review that expects to use about12 points of every window it draws from. Itdraws on the account-wide windows and on ModelB's own allowance.All models, 5-hour window1238 used, 10 reserved by other jobs, 10 kept inreserve, 42 free. Read 2 min ago.Fits: 42 freeAll models, weekly windowneeds 1271 used, 15 reserved by other jobs, 10 kept inreserve, 4 free. Read 2 min ago.Does not fit: 4 free, needs 12Model B only, weekly window1230 used, 0 reserved by other jobs, 10 kept in reserve,60 free. Read 3 min ago.Fits: 60 freeusedreserved by other jobskept in reservefreethis job's 12Decision: WAITThe weekly window of All models has 4 pointsfree and the job needs 12. Room in the other twowindows does not help. The agent tries anothermodel family from its list, or waits for a resetand asks again.

    How to read this: each bar is one window of 100 points, split into what is used, what other jobs have reserved, what I keep in reserve and what is free. The copper block is the job. A dashed block is a job that does not fit.

    Method and data

    Free points are what remains after what is used, what other jobs have reserved and what is kept in reserve. A window fits the job when its free points are at least the 12 the job expects. The decision is wait if any window it draws from does not fit, or if a reading is UNKNOWN.

    Two agents, one gap

    Picture two agents looking at the same account a moment apart. Both see room, both start, and between them they overshoot. Checking is not enough. When an agent starts work through headroom run, or explicitly requests a lease, Headroom checks and reserves capacity in one operation. That reservation (a lease) covers what the job expects to use and is taken under one SQLite write lock, so the second agent sees the first one’s claim. With headroom run, the reservation is released when the command exits. Agents requesting a lease directly must release it themselves; otherwise it expires.

    I want to be straight about what that is. A lease is a promise between agents that bother to ask. It doesn’t throttle a model or stop a job at its estimate, and it does nothing about a tool that ignores Headroom. The vendor still holds the real limit.

    What stops two agents taking the same room?

    The first job reserves its 12 points as it is admitted. When the second asks, only 3 are free, so it is refused.

    Reservation arithmetic in three framesIllustrative example with synthetic data, simplified, with no pacing restriction. One shared window has 40 points remaining. Frame 1: 15 points are reserved for other work and 10 are kept in reserve, so 15 are free. Frame 2: a job that expects 12 points asks and is admitted, leaving 3 free. Frame 3: a second 12-point job asks and is refused, because only 3 are free.Illustrative example · synthetic data40 points remaining in one shared window1. Nothing asked yet15 reserved by others10 kept in reserve15 free15 free2. Job A asks for 12: admitted1510A 123Admitted. 3 free.3. Job B asks for 12: refused1510A 123Job B: 12Refused. 3 free, needs 12.reserved by other jobskept in reservefreeJob A
    Reservation arithmetic in three framesIllustrative example with synthetic data, simplified, with no pacing restriction. One shared window has 40 points remaining. Frame 1: 15 points are reserved for other work and 10 are kept in reserve, so 15 are free. Frame 2: a job that expects 12 points asks and is admitted, leaving 3 free. Frame 3: a second 12-point job asks and is refused, because only 3 are free.Illustrative example · synthetic data40 points remaining in one shared window1. Nothing asked yet15 others10 kept15 free15 free2. Job A asks for 12: admitted1510A 12Admitted. 3 free.3. Job B asks for 12: refused1510A 12Job B: 12Refused. 3 free, needs 12.reserved by other jobskept in reservefreeJob A

      How to read this: the bar is the 40 points remaining in one shared window. Hatched is reserved for other work, tinted is kept in reserve, and copper is the first job. The dashed block is the second job, which does not fit.

      Method and data

      The numbers are simplified arithmetic, not a claim about what a real task costs. A reservation is a commitment among agents that use Headroom. It does not throttle the model or stop a job at that amount, and the vendor still controls the real account limit.

      My own rules went stale too

      One refusal was correct by an old rule and wrong for what I wanted. I had set aside part of an allowance. Later a reset was available and I had work queued, but the reserve was still in the config. Two sessions ran into it before I understood why.

      What I wanted was a refusal that explains itself. Reserves now carry a reason, a date and an expiry, and can depend on whether a usable banked reset exists. When Headroom says no, it points at the rule. That beats arguing with a red light.

      There’s a mode for the opposite case too, where I have a real queue to finish before a reset and spreading work evenly would waste the window. It still respects the caps. I don’t want an agent inventing work to empty a meter. Unused allowance is information, not a target.

      Getting off the screen

      Everything so far still assumed I was looking. The Tesla comparison only works if the car also tells me when something changes.

      So Headroom can send a message to my phone. The messages worth having are about things I would not notice, or would notice later than I’d like: a weekly window that resets early and unannounced, a free reset credit that shows up, a source that has stopped answering, a usage threshold crossed. I always find out about a reset eventually. The point is finding out while there is still time to make the most of it. An early reset arrives like this:

      Headroom

      Unscheduled reset

      Codex weekly is back to 0% (was 88%).

      Plan again: a full week of capacity appeared.

      03:24

      Example notification · synthetic values

      Channels and safeguards

      Messages go out through Telegram, ntfy or a webhook, and nothing is sent until you pick a channel. A reset can need a second vendor reading before Headroom believes it. The same kind of event for the same window is sent at most once every six hours, because a nudge you learn to ignore is worse than none. Quiet hours are supported, and the Telegram bot token stays in the system keychain, read at the moment of sending.

      Agents can already be refused work, or start it through headroom run, but they do not yet rearrange their plans when a window resets. Reset notifications currently come to me. Automatic replanning after a reset is the next thing I want to explore.

      Where it stands

      The car’s navigation knows where the chargers are. Headroom reads some vendor endpoints that are undocumented. My tests cover the responses I’ve seen so far; those endpoints can still change. Its estimates come from recent burn and from what similar finished jobs used, reported with a sample count and no promise. A dependable conversion from tokens to subscription quota is still future work.

      Within those limits, it already does the job I built it for. It is for anyone who runs more than one agent or more than one subscription and would rather not be the one watching the meters. It helps most when work runs unattended: overnight, on a trip, or while you are in a meeting.

      If you want to try it, install it, run headroom setup once to find your accounts and register the MCP server, then run headroom to see your meters and headroom can <action-class> to ask whether a job fits. If you would rather look first, the repository has a demo home with synthetic data that needs no logins. Headroom is MIT licensed, works with any agent that can run shell commands, and macOS is the main platform. Claude Code is the MCP client I’ve tested.

      If you try it, tell me what’s missing or where it gets a decision wrong.

      Headroom on GitHubnpm install -g headroomd

      I work on products, lead teams and build with AI. More about me and my own AI tools on martijnhermans.nl. Back to Field Notes.