How to install headroom?
headroomlabs-ai/headroom
$git clone https://github.com/headroomlabs-ai/headroomInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install headroom by running `git clone https://github.com/headroomlabs-ai/headroom`, then use it for the current task and follow its documentation at https://github.com/headroomlabs-ai/headroom.
README.md
| 1 | <div align="center"><pre> |
| 2 | ██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ |
| 3 | ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ |
| 4 | ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ |
| 5 | ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ |
| 6 | ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ |
| 7 | ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ |
| 8 | The context compression layer for AI agents |
| 9 | </pre></div> |
| 10 | |
| 11 | <p align="center"><strong>60–95% fewer tokens (for JSON data), 15-20% fewer tokens (for coding agents) · library · proxy · MCP · content-aware compressors · local-first · reversible</strong></p> |
| 12 | |
| 13 | <p align="center"> |
| 14 | <a href="https://github.com/chopratejas/headroom/actions/workflows/ci.yml"><img src="https://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a> |
| 15 | <a href="https://app.codecov.io/gh/chopratejas/headroom"><img src="https://codecov.io/gh/chopratejas/headroom/graph/badge.svg" alt="codecov"></a> |
| 16 | <a href="https://pypi.org/project/headroom-ai/"><img src="https://img.shields.io/pypi/v/headroom-ai.svg" alt="PyPI"></a> |
| 17 | <a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg" alt="npm"></a> |
| 18 | <a href="https://huggingface.co/chopratejas/kompress-v2-base"><img src="https://img.shields.io/badge/model-Kompress--v2--base-yellow.svg" alt="Model: Kompress-v2-base"></a> |
| 19 | <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a> |
| 20 | <a href="https://headroom-docs.vercel.app/docs"><img src="https://img.shields.io/badge/docs-online-blue.svg" alt="Docs"></a> |
| 21 | </p> |
| 22 | |
| 23 | <!-- mcp-name: io.github.headroomlabs-ai/headroom --> |
| 24 | |
| 25 | <p align="center"> |
| 26 | <a href="https://headroom-docs.vercel.app/docs">Docs</a> · |
| 27 | <a href="#get-started-60-seconds">Install</a> · |
| 28 | <a href="#proof">Proof</a> · |
| 29 | <a href="#agent-compatibility-matrix">Agents</a> · |
| 30 | <a href="https://discord.gg/yRmaUNpsPJ">Discord</a> · |
| 31 | <a href="llms.txt">llms.txt</a> |
| 32 | </p> |
| 33 | |
| 34 | <p align="center"><sub> |
| 35 | <b>AI agents / LLMs:</b> read <a href="llms.txt"><code>/llms.txt</code></a> here, or fetch <a href="https://headroom-docs.vercel.app/llms.txt">the live index</a> / <a href="https://headroom-docs.vercel.app/llms-full.txt">full docs blob</a>. |
| 36 | </sub></p> |
| 37 | |
| 38 | --- |
| 39 | <p align="center"><a href="https://trendshift.io/repositories/20881" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20881" alt="chopratejas%2Fheadroom | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a></p> |
| 40 | |
| 41 | Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens. |
| 42 | |
| 43 | <p align="center"> |
| 44 | <img src="HeadroomDemo-Fast.gif" alt="Headroom in action" width="820"> |
| 45 | <br/><sub>Live: 10,144 → 1,260 tokens — same FATAL found.</sub> |
| 46 | </p> |
| 47 | |
| 48 | ## What it does |
| 49 | |
| 50 | - **Library** — `compress(messages)` in Python or TypeScript, inline in any app |
| 51 | - **Proxy** — `headroom proxy --port 8787`, zero code changes, any language |
| 52 | - **Agent wrap** — `headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode` in one command; undo with `headroom unwrap <tool>` |
| 53 | - **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client |
| 54 | - **Cross-agent memory** — shared store across Claude, Codex, Gemini, Grok, auto-dedup |
| 55 | - **`headroom learn`** — mines failed sessions, writes corrections to `CLAUDE.local.md` (default, gitignored) or `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `GROK.md` |
| 56 | - **Output token reduction** — trims what the model *writes back* (not just what you send): drops ceremony/restated code and skips deep "thinking" on routine steps. See [Output token reduction](#output-token-reduction-cut-what-the-model-writes-back). |
| 57 | - **Reversible (CCR)** — originals |
Related
6 picksType
- langchain-mcp-adaptersMake Anthropic Model Context Protocol (MCP) tools compatible with LangChain and LangGraph agents.Jul 2026
- mcporterTypeScript runtime and CLI for connecting to configured Model Context Protocol servers.Jul 2026
- mcp-proxyA MCP server which proxies requests to a remote MCP server over streamable HTTP or SSE.Jul 2026
- mcp-atlassianThe Model Context Protocol (MCP) Atlassian integration is an open-source implementation that bridges Atlassian products (Jira and Confluence) with AI language models following Anthropic's MCP specification.Jul 2026
- open-webuiOpen WebUIJul 2026
- rulesyncUnified AI rules management CLI tool that generates configuration files for various AI development toolsJul 2026
