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.

Invite-only beta · Headroom 0.9.76 or later · macOS 15 Sequoia or later

Works with Claude Code, Codex, Cursor and any MCP client →
Claude Code~/checkout-web

Before starting, check Headroom and tell me if this job fits in my 5-hour window.

Calledheadroom_limits Read-only

Claude CodePersonal · Max 20×
Ready
5-hour58% left
13 aheadResets 2h 14m

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 MCP3 tools · read-only
headroom_limits

Your 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.

Claude CodePersonal · Max 20×
Ready
5-hour58% left
13 aheadResets 2h 14m
CodexPersonal · Pro 20×
Ready
Weekly52% left
5 behindResets 4d 0h
headroom_usage

Tokens and API value over time

The last few days, up to 30, grouped by tool, account, model, project or day.

Last 7 daysby tool

Codex232.0M$286
Claude Code202.1M$412
Cursor18.4M$29

452.5M tokens$727 API value

headroom_projects

What 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

checkout-web43%$1,184
Opus 5.5 · 18 days
ios-app30%$836
Sol 6 · 14 days
data-pipeline14%$382
Sol 6 · 9 days

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 a long job

“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.

Settings AI agentsIn Headroom
  • Claude CodeTerminal and the Claude desktop app's Code tab · MCP and skill
    ConnectedRemove
  • CodexCodex CLI and app · MCP and skill
    Connect
  • CursorCursor's agent · MCP
    Connect
  • 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 CodeRun in your terminal.
claude mcp add --scope user headroom -- /Applications/Headroom.app/Contents/Helpers/HeadroomTracker mcp
CodexRun in your terminal.
codex mcp add headroom -- /Applications/Headroom.app/Contents/Helpers/HeadroomTracker mcp
Cursor, the Claude desktop app and othersAdd to the client's MCP config: ~/.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.

Where your numbers go Read-only

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

HeadroomKeeps your numbers up to date
Headroom MCPServes them, read-only
Your agentReads them when you ask, or before a job

Your agent's provider

Its AI modelSees what your agent read, like the rest of the chat

Questions

Headroom MCP, answered.

Anything else? Write to hello@headroom.bar.

Questions12 answers

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.

Your invite and the odd update. No spam, no sharing.

For macOS 15 Sequoia and later · Works with ChatGPT, Claude Code and 9 more