Headroom, on the stand

Headroom sits between a coding agent and the model and shrinks what the agent is about to send: tool output, logs, JSON, files and search results. The project is published by Headroom Labs under the Apache 2.0 license. It ships as a Python package with a headroom command, a TypeScript library, a proxy, a headroom wrap command for agents such as Claude Code and Codex, and an MCP server. The README says compression runs on your machine and that originals are cached locally so the model can ask for them back.

The top contributor by commits is Tejas Chopra, whose GitHub profile lists Netflix as his employer. The project is published by Headroom Labs, not by Netflix.

The README makes its own claims: 21% to 57% fewer tokens across four agent scenarios, over 90% on repeated JSON arrays and log lines, and accuracy tables on GSM8K and TruthfulQA that it says show no detectable difference. Those are the maker's numbers. We did not repeat them.

Two things to know before you install. An anonymous usage beacon is on by default. The README says it never sends prompts, code or file paths, and HEADROOM_BEACON=off or DO_NOT_TRACK=1 turns it off. There is also a paid Enterprise plan for teams; the open-source version is free.

The test. MODEL installed headroom-ai 0.41.0 from PyPI into a fresh Python 3.13 environment on Linux. It took 19 seconds. We switched the beacon off, called no model and used no API key. We ran the library's compress() function on three tool results and counted tokens with OpenAI's tiktoken.

A 240-line service log with one real error, pulled by a shell tool: 10,145 tokens down to 1,759, 83% fewer. Headroom kept 41 lines, including the error line exactly as written. In the same Python process we got the full original back from its local store, byte for byte.

A 300-order JSON API response with one failed payment: 37,700 tokens down to 12,836, 66% fewer. Nothing was dropped. Headroom rewrote the list as one header plus one compact row per order, and the failed order kept its ID, amount and decline reason.

A 2,019-line Python file (httpx's client): no change. The docs say code passes through unless you turn code compression on, and anything read through a read_file or Read tool is skipped so the agent can edit exact bytes. That log, read through a read_file tool, also came back untouched. When we called the code compressor directly, the file dropped 23%, from 13,702 to 10,539 tokens. It was still valid Python, with all 88 function and class lines kept.

The catch. The note Headroom appends to a trimmed log said "200 lines omitted: 1 ERROR, 14 WARN, 166 INFO." It had kept the only error, it dropped 9 warnings, not 14, and it dropped 199 lines in all. The counts look like totals for the whole file. An agent could read that note and go looking for an error that was never hidden.

What we did not test. We did not run headroom wrap or the proxy with a real agent and a real model, so we cannot tell you whether answers stay the same. We did not test the Kompress text model, image compression, memory, headroom learn or the MCP server.

The verdict. Try it if your agent spends its context on long logs and big JSON responses. That is where it saved us the most. Expect little on source files, and switch the beacon off if you want nothing to leave the machine.