What each piece is
| Piece | What it is | How you turn it on |
|---|---|---|
| Headroom app | A menu bar app that runs the compression proxy and routes your agents through it. | Download and open once. It then applies to every session. |
| Headroom CLI plugin | A Claude Code startup hook that starts the CLI's proxy if it is not running. | headroom init claude (add -g for every project). |
| Ponytail | An open-source plugin that makes Claude Code and Codex write less code. | One-click add-on, or install by hand. |
| RTK | A command wrapper that trims noisy terminal output. | One-click add-on in the Headroom app. |
| MarkItDown | A converter that turns PDFs and Office files into compact Markdown. | One-click add-on in the Headroom app. |
Why the compression lives in a proxy
A plugin or skill only sees what the agent hands it, and only in sessions where it is active. A proxy sits on the request path, so it sees each request the way the model does: the whole assembled context, every time. That gives it three things. Coverage is complete, including sub-agent runs, which is where token costs spike because they lose the parent session's prompt cache. Nothing needs enabling per session. And compression can be reversible: the originals stay on your machine, and a retrieval tool lets the model fetch the full detail when it needs it.
If you came looking for a skill
You probably want Ponytail. It works with Claude Code and Codex, has slash commands and intensity levels, and works on the part of the bill Headroom's compression does not touch: the code the agent writes. The guide covers the one-click and manual installs.
Is there an MCP server?
Yes, in a supporting role. The open-source CLI can register itself as an MCP server with headroom mcp install, and the app sets up an MCP entry for retrieval so the model can pull back compressed content. The compression itself happens in the proxy, not through MCP tool calls, which is why it works without the agent's cooperation.
What this means in practice
Install the app once and every Claude Code and ChatGPT Codex session is compressed from then on, including after a restart, then turn on the add-ons you want from one screen. If you would rather run the engine yourself, the install guide covers the CLI, and app vs CLI compares the two. If a coding agent is doing the setup, the agent runbook gives it every command.