Repolode
Submit
headroomlabs-ai

headroomlabs-ai/headroom

Compresses tool outputs, logs, files and RAG chunks before they reach an LLM, as a library, proxy or MCP server.

View on GitHubWebsite
Stars
76,105
Forks
5,915
Open issues
482
Last commit
3 days ago

What is it?

Headroom is a context compression layer for AI agents and LLM applications. It compresses tool outputs, logs, RAG chunks, files and conversation history before they are sent to the model, and the compression runs locally on the user's machine. A content router detects the type of each payload: JSON goes to SmartCrusher, source code to an AST-aware CodeCompressor, and prose to the Kompress-v2-base model.

It can be used as an inline Python or TypeScript library through compress(messages), as a drop-in proxy that needs no code changes, through headroom wrap for coding agents such as Claude Code, Codex, Cursor and Aider, or as an MCP server. Compression is reversible: originals are cached locally and the model can retrieve them on demand.

Savings depend on the payload. The project's benchmarks show 21% to 57% fewer tokens on sample agent workloads, and repetitive JSON and log output compresses much more. Prose and already-dense text see little reduction.

Key features

  • 01Content-type routing that picks a compressor for JSON, code or prose.
  • 02Reversible compression, with originals cached locally and retrievable on demand.
  • 03Zero-code-change proxy and one-command wrappers for popular coding agents.
  • 04Python and TypeScript libraries exposing compress() for inline use.
  • 05MCP server with compress, retrieve and stats tools.
  • 06Local processing, so prompt and file content is not sent to a service for compression.

Use cases

  • Reducing token costs for coding agents such as Claude Code or Cursor during long sessions with heavy tool output.
  • Compressing log dumps or large JSON search results before sending them to a model for debugging.
  • Shrinking retrieved RAG chunks in an existing LangChain or LiteLLM pipeline.
  • Routing several agents through one shared proxy and memory layer.

Quick start

  1. 1

    Install the CLI with uv

    uv tool install --python 3.13 "headroom-ai[all]"
  2. 2

    Or install the Python package with pip

    pip install "headroom-ai[all]"
  3. 3

    Start the drop-in proxy on port 8787

    headroom proxy --port 8787
  4. 4

    Check the installation with the health check

    headroom doctor

Things to know

  • Savings vary widely; prose and already-dense output compress very little.
  • The README's compression benchmarks are self-reported and run on specific seeded scenarios.

Topics

#llm#context-window#token-optimization#rag#mcp#coding-agents#proxy#prompt-engineering#agent#ai

FAQ

What is headroom?
Compresses tool outputs, logs, files and RAG chunks before they reach an LLM, as a library, proxy or MCP server. Headroom is a context compression layer for AI agents and LLM applications. It compresses tool outputs, logs, RAG chunks, files and conversation history before they are sent to the model, and the compression runs locally on the user's machine. A content router detects the type of each payload: JSON goes to SmartCrusher, source code to an AST-aware CodeCompressor, and prose to the Kompress-v2-base model.
Is headroom free to use? What license does it have?
headroom is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is headroom still maintained?
Actively maintained. The last commit to headroom was on Oct 17, 2026.
What can I use headroom for?
Reducing token costs for coding agents such as Claude Code or Cursor during long sessions with heavy tool output. Compressing log dumps or large JSON search results before sending them to a model for debugging. Shrinking retrieved RAG chunks in an existing LangChain or LiteLLM pipeline. Routing several agents through one shared proxy and memory layer.
How do I install headroom?
Install the CLI with uv: uv tool install --python 3.13 "headroom-ai[all]" Or install the Python package with pip: pip install "headroom-ai[all]" Start the drop-in proxy on port 8787: headroom proxy --port 8787 Check the installation with the health check: headroom doctor
Where can I get headroom?
The source code and installation instructions are on GitHub: https://github.com/headroomlabs-ai/headroom

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects