
Ask your AI about your AI usage.
Connect Claude Code, Codex or Cursor to Headroom, and your agent can check your limits, your pace and what each project used in API value. It runs on your Mac, and it's read-only.
Before starting, check Headroom and tell me if this job fits in my 5-hour window.
Calledheadroom_limits
Read-only

Current reading · updated 1 min ago
It fits. Personal has 58% of its 5-hour limit left, 13 points ahead of an even pace, and it resets in 2h 14m.
Short answer
What is Headroom MCP?
Headroom MCP is a local, read-only MCP server built into Headroom for Mac. It gives your AI agent the numbers Headroom shows: every account's limits and pace, and tokens and API value by tool, model and project. Connect Claude Code, Codex or Cursor in one click, then ask in plain English. Nothing goes to Headroom's servers.
- Settings › AI agentsOne click for Claude Code, Codex, Cursor and Claude app chat
- HeadroomTracker mcpThe same server, for any other MCP client
- HeadroomRuns in your menu bar and keeps the numbers fresh
The tools
What can your agent read from Headroom?
Three tools, all read-only. Your agent picks the one that fits your question, and every reply says how fresh its numbers are.
headroom_limitsYour limits, right now
Every connected account: % left of each 5-hour, weekly and model limit, when each resets, whether you're ahead or behind an even pace, and whether a reading is current or last known.
headroom_usageTokens and API value over time
The last few days, up to 30, grouped by tool, account, model, project or day.
Last 7 daysby tool
452.5M tokens$727 API value
headroom_projectsWhat each project cost
Tokens, API value and share for each project or client, with its top models, tools and accounts, and the days it was worked on.
Last 30 daysby project
API value is what the tokens would cost at pay-as-you-go API prices, not what your plan charges. Illustrative data.
Ask it
What can you ask your agent?
Plain English works. Your agent calls the right tool, reads the numbers and answers. Ask it yourself, or have it check before a long job.
“How much Claude do I have left before my weekly reset?”
headroom_limits
Personal has 64% of its weekly limit left and resets in 5d 7h. That's 12 points behind an even pace.
“Which of my accounts should I use for this long refactor?”
headroom_limits
Personal. It has 58% of its 5-hour limit left and resets in 2h 14m. Work is down to 22%.
“What did each client cost in API value over the last 30 days?”
headroom_projects
checkout-web came to $1,184 (43%), ios-app $836 (30%) and data-pipeline $382 (14%). That's API value, not what your plan charged.
“Which model used the most tokens this week?”
headroom_usage
Sol 6 in Codex: 136.7M of your 452.5M tokens (30%). Opus 5.5 in Claude Code is next with 118.4M.
“Am I on pace for my Codex weekly limit?”
headroom_limits
A little behind. Personal has 52% left with 4d 0h to go. An even pace would leave 57%, so you're 5 points behind.
“Before starting, check Headroom and tell me if this job fits in my 5-hour window.”
headroom_limits
It should. Personal has 58% of its 5-hour limit left, 13 points ahead of pace, and it resets in 2h 14m.
Answers use illustrative data.
Connect
Connect your agent in one click.
In Headroom 0.9.76 or later, open Settings › AI agents and click Connect next to your agent. Claude Code and Codex get the skill too. Nothing changes until you click, and Remove undoes it.
Claude CodeTerminal and the Claude desktop app's Code tab · MCP and skillConnectedRemove
CodexCodex CLI and app · MCP and skillConnect
CursorCursor's agent · MCPConnect
Claude app chatChats in the Claude desktop app · MCP (restart Claude after connecting)Connect
Set it up by hand
Using another MCP client, or prefer the terminal? Run Headroom's helper with the argument mcp. It lives at /Applications/Headroom.app/Contents/Helpers/HeadroomTracker. In Settings › AI agents, Copy setup for another tool copies the same JSON for you.
claude mcp add --scope user headroom -- /Applications/Headroom.app/Contents/Helpers/HeadroomTracker mcpcodex mcp add headroom -- /Applications/Headroom.app/Contents/Helpers/HeadroomTracker mcp~/.cursor/mcp.json for Cursor, claude_desktop_config.json for the Claude desktop app.{
"mcpServers": {
"headroom": {
"command": "/Applications/Headroom.app/Contents/Helpers/HeadroomTracker",
"args": ["mcp"]
}
}
}The skill
A skill that knows when to check.
Connect Claude Code or Codex and Headroom adds its skill too, an Agent Skills SKILL.md. It teaches your agent when to check Headroom and how to read what it gets back.
- Checks before a long jobLooks at your limits and pace before it starts something big.
- Answers cost questions“What did client X cost this month?” becomes a project breakdown in API value.
- Explains API valueWhat the tokens would cost at pay-as-you-go API prices, never mixed up with what your plan charges.
- Works without the MCPIf the MCP isn't connected, the skill gets the same numbers from Headroom's command line.
Privacy
What does your agent get to see?
Your numbers, read-only. They stay on your Mac until your agent reads them, and Headroom MCP sends nothing to Headroom's servers.
What Headroom MCP shares
- Your numbersLimits, pace, tokens and API value, with model, project and account names.Read-only
- Your prompts, code and filesThey aren't in Headroom's data, so the MCP has none to give.Not in the data
- Headroom's serversHeadroom MCP sends them nothing.Never
- Your agent's AI providerWhatever your agent reads, like usage numbers and project and account names, goes to its provider like anything else in the conversation.What it reads
- How fresh it isHeadroom needs to be running to keep the numbers current. Every reply says how fresh they are.In every reply
On your Mac
Your agent's provider
01 / 12
What is an MCP server?
MCP, the Model Context Protocol, is how AI agents like Claude Code, Codex and Cursor use outside tools. Headroom's MCP server gives them read-only access to the numbers Headroom shows: your limits, your pace, and tokens and API value by project and model.
02 / 12
Which agents does Headroom MCP work with?
Claude Code (in the terminal and the Claude desktop app's Code tab), Codex (CLI and app), Cursor's agent and chats in the Claude desktop app connect in one click, in Settings › AI agents. Any other MCP client can run Headroom's helper, HeadroomTracker, with the argument mcp.
03 / 12
Does Headroom MCP send my data anywhere?
Not to Headroom's servers. It runs on your Mac and serves the numbers Headroom already has there. Whatever your agent reads, like usage numbers and project and account names, goes to that agent's AI provider, like anything else in the conversation.
04 / 12
Can my agent see my prompts or code through Headroom?
No. Prompts, replies, code and file contents aren't in Headroom's data, so the MCP has nothing of the sort to give. It serves limits, token counts, API value, and model, project and account names.
05 / 12
Can my agent change anything through Headroom?
No. Headroom MCP is read-only. Your agent can read the numbers, and that's all.
06 / 12
Does Headroom need to be running?
Yes. Headroom keeps the numbers up to date, and the MCP serves what it has. Every reply says how fresh the numbers are, and whether each limit is a current reading or the last one Headroom saw.
07 / 12
What is API value?
What your tokens would cost at pay-as-you-go API prices. It isn't what your plan charges. It puts every tool, model and project on the same scale, so you can compare them.
08 / 12
Does it cover more than one account?
Yes. headroom_limits returns every connected account, each with its own limits and resets, and headroom_usage can group tokens and API value by account.
09 / 12
How do I get the Headroom skill?
Connect Claude Code or Codex in Settings › AI agents, and Headroom adds its skill along with the MCP. The MCP gives your agent the numbers; the skill teaches it when to check them and how to explain API value. If the MCP isn't connected, the skill can read the same data through Headroom's command line.
10 / 12
How do I remove it?
In Settings › AI agents, click Remove next to the agent. That undoes what Connect added.
11 / 12
Which version of Headroom do I need?
Headroom 0.9.76 or later, on macOS 15 Sequoia or later. Headroom is free while it's in beta.
12 / 12
Does it work with cloud agents?
Not yet. Headroom MCP runs on your Mac, for agents that run there. A hosted connection for cloud agents is coming for teams.
Give yourself some headroom.
Headroom is in a private beta. Leave your email and we'll send your invite as we let people in.