Markdown version of https://extraheadroom.com/headroom-vs-caveman

# Headroom vs Caveman: what's the difference?

Caveman began as a skill that made agents reply tersely, which sat alongside input-side compression rather than competing with it. Its proxy and engine now compress what the model reads as well, so the two tools overlap and the comparison is a real one.

## Quick answer

They overlap more than they used to. Both now run a local proxy that compresses agent context before it reaches the model, and both keep the original content recoverable rather than discarding it. The practical difference is packaging and scope: **Headroom** is a finished desktop app that sets itself up and covers Claude Code and ChatGPT Codex deeply (plus experimental OpenCode and Grok Build connectors), while **Caveman** is a broad open-source toolkit spanning many agents with more surface area and more setup. Both run locally, so the quickest test is running each on a session you already do.

## Where they overlap

Four things they share:

- **Both are local proxies.** Each sits between your agent and the provider and rewrites the request on the way out. Neither ships your prompts to its own backend to do the work.
- **Both compress by content type.** Logs, JSON, code, and search results each compress differently, and both tools route them through different rules rather than applying one blunt heuristic.
- **Both are reversible.** Headroom attaches a retrieval tool so the model can pull back original content on demand; Caveman keeps original bytes in a content-addressed store recoverable through its own retrieval tool. Neither is throwing information away.
- **Both pass subscription logins through.** You are not forced onto API billing to use either one.

If you were expecting an argument that Caveman does not really do what Headroom does, this is not that page.

## Side by side

| | Headroom | Caveman |
| --- | --- | --- |
| Shape | A menu bar app for macOS, Windows, and Linux, built on an open-source CLI. | An open-source toolkit: skill, proxy, engine, CLI, and companion projects. |
| Setup | Download, drag to Applications, open once. No terminal. | Install via npm or the skill installer, then configure per agent. |
| Agent coverage | Claude Code and ChatGPT Codex covered deeply; OpenCode and Grok Build as experimental connectors. | Broader: several agents wrapped natively, more via rule files. |
| Output-side savings | Via the Ponytail add-on (writes less code). | Via the original skill (writes fewer words). |
| Keeping it running | Menu bar app, starts with your machine, auto-updates. | You manage the install and updates. |
| Visibility | Activity dashboard, per-session savings, usage-window tracking. | `stats` command and benchmark tooling. |
| Licence | Engine is open source (Headroom CLI); the app is paid. | Skill is MIT; proxy and engine are BSL-1.1. |

## What Caveman does that Headroom does not

Caveman covers more agents natively, including Gemini CLI and Aider, where Headroom's deep coverage is Claude Code and ChatGPT Codex, with its OpenCode and Grok Build connectors newer and still marked experimental. It also ships features with no Headroom equivalent: rendering dense text to images for vision models, compressing skill and memory files so each session loads lighter, a browse driver over a compressed accessibility tree, and cross-session memory. If any of those map to your workflow, Headroom will not cover them.

## What Headroom does that Caveman does not

The difference is finish rather than cleverness. Headroom is a desktop app, signed and notarized on macOS, that installs in one step, sets up its own routing, starts with your machine, updates itself, and shows you an activity view of what it saved and where, including how much of your 5-hour and weekly windows you have left. There is no terminal step, nothing to keep alive, and nothing to remember to update.

That is packaging, not a technical moat: our own [open-source CLI](/headroom-desktop-vs-cli) is free, and we say on that page that you are paying for the packaged app rather than the engine. The same logic applies here. If assembling and maintaining your own setup is something you enjoy, that path exists in both ecosystems.

## About the benchmark numbers

Both projects publish savings percentages, and you should discount both by default. Self-reported compression figures depend enormously on the workload measured: a session heavy on logs and file reads compresses far better than a conversational one, so anyone can pick a favourable mix. Caveman's own contributor rules are notably strict on this, reserving their strongest evidence label for real production traffic and refusing it for offline runs, which is more discipline than most tools in this space show.

The only number that settles it is yours. Run a task you actually do, with each tool, and compare. Both are local and both are quick to remove, so the test costs you an afternoon at most.

## Can you run both?

Not usefully in the same session. Two proxies compressing the same request is not additive: they would be fighting over the same tokens, and you would lose the ability to attribute savings to either. Pick one for the input side.

The output side is different. Caveman's skill makes the agent write fewer words; [Ponytail](/ponytail-claude-code) makes it write less code. Those stack with each other and with whichever input-side proxy you choose, because they never touch the same tokens. See [how the input, output, and terminal-side tools divide the work](/headroom-vs-ponytail).

## Which should you pick?

Choose **Headroom** if you live in Claude Code or ChatGPT Codex and want this handled rather than administered: one download, no config, updates that arrive on their own, and a clear view of what you saved. Choose **Caveman** if you use agents Headroom does not cover, like Gemini CLI or Aider, or want its experimental compression features and are happy to assemble them yourself. Note the licensing: Caveman's skill is MIT, but its proxy and engine are BSL-1.1, while the Headroom CLI engine is Apache 2.0.

The category is moving quickly. If you are reading this some months after it was written, check both projects directly rather than trusting a comparison page, including this one. And if you are weighing the wider field rather than just these two, the [Caveman alternatives](/caveman-alternatives) page covers the free and DIY routes as well.