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.
Generative contour artwork.
Listen to this note
6 minutes · two hosts talk it through
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)
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.
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.
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:24Example 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.
npm install -g headroomdI work on products, lead teams and build with AI. More about me and my own AI tools on martijnhermans.nl. Back to Field Notes.