Headroom: compress the logs and documents your agent reads before they reach the model, cutting tokens by up to 95%Headroom：把智能体读到的日志与文档先压缩再喂给模型，token 最高省 95%

The expensive part of an agent is usually not the model but the noise you feed it: a failing test log, a JSON blob tens of thousands of tokens long, a pile of retrieved documents — the vast majority of which contributes nothing to the final answer.

Headroom's idea is to make compression an infrastructure layer before the model: tool output, logs, files, RAG chunks and session history are filtered before being sent, so answer quality stays roughly the same while your bill and window usage both drop.

The official README makes it concrete: a 10,144-token log dump compressed to 1,260 tokens, with the FATAL line preserved exactly.

It offers three ways in: wrapping the command line (handing tool output to it for compression), using it as a library in code (from headroom import compress), and plugging into mainstream coding agents.

Compression runs on your own machine and never uploads prompts or file contents. For structured text such as logs it groups by line type, dedupes and truncates, while rules guarantee that "lines you cannot lose" are always kept.

There is also headroom learn: it mines failed sessions and writes corrections back into your configuration so the same class of mistake is less likely next time.

Install: the PyPI package is headroom-ai, with a same-named npm package. Once installed, run a check command first to see how much it saves in your real workload.

On x86/x86_64 machines some ONNX-backed features require AVX2 CPU support; older servers or some Docker/QEMU environments may not qualify, and the README devotes a section to this.

When should you skip it? If you only use a single vendor's built-in compaction and do not need a unified cross-tool compression layer, there is no point adding another layer.

The download button provides the official PyPI source distribution (sdist) headroom-ai 0.40.0, including the full Python implementation, evaluation scripts and docs. Unzip it and follow the README's 60-second quickstart.

This article is compiled from public sources and ships with the matching resource. Product features and pricing are subject to the official page. Resources are for learning and exchange only — please respect the original license.