Headroom compresses agent input locally: 21–57% fewer input tokens across four agent scenarios, over 90% on repeated JSON and log lines
Synopsis
Headroom compresses what an AI agent reads, including tool outputs, logs, RAG chunks, files and conversation history, before it reaches the LLM, aiming for the same answers with fewer input tokens. Across four agent scenarios it measured 21–57% fewer input tokens, over 90% on repeated JSON arrays and log lines, and little on prose. Compression runs in-process on the local machine, and originals are cached locally so the model can retrieve them when needed.
Interpretation
Headroom compresses the content an agent reads, covering tool outputs, logs, RAG chunks, files and conversation history, before the prompt reaches the LLM, claiming the same answers with fewer input tokens. Previously this content went to the model as-is, so input tokens grew with tool output and logs. Across four agent scenarios it measured 21–57% fewer input tokens, over 90% on repeated JSON arrays and log lines, and little on prose.
Compression is routed by content type: JSON, source code and prose each go to a different compressor. A content router first detects the content type and then selects the matching compressor, rather than applying one compression to all text. SmartCrusher handles JSON, CodeCompressor handles source code via an abstract syntax tree, and Kompress-v2-base handles text; compression runs locally and sends no prompt or file content out.
Originals are kept in a local cache, and the model can call a retrieval tool to get the full text when needed. Compression is not a one-way discard; the reversible cache lets the model fetch the original when full text is required. CCR stores originals locally and the model can call headroom_retrieve; setting HEADROOM_OFFLINE=1 gives a zero-network run.
Perspective
The demonstrated scope is input-token measurements across four agent scenarios and high compression on repeated JSON arrays and log lines; compression runs in-process locally, with a zero-network mode available.
Compression has little effect on ordinary prose; 21–57% is a range across four scenarios, not a fixed value for any single one; the same-answers claim comes from the project's own measurement description.