All Repos
MCP & ToolingPythonApache-2.0

headroom

headroomlabs-ai/headroom · Updated

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

headroomlabs-ai/headroom is a Python repository in the MCP & Tooling category with 78,219 stars and 6,092 forks on GitHub, released under the Apache-2.0 license, last updated today.

#agent#ai#anthropic#claude-code#compression#context-engineering#context-window#cursor
View on GitHub 78kGitHub stars

How to install headroom in your AI client

Setup for Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline and VS Code — copy-paste ready.

How to install headroom in Claude CodeAnthropic's agentic CLI

  1. Clone & open

    bash
    git clone https://github.com/headroomlabs-ai/headroom.git
cd headroom
claude

  2. Let Claude read it

    Ask “/init” to generate a CLAUDE.md, then have Claude explain, run, or extend the codebase. It reads files on demand.

Documentation

Full README

<b>Quickstart</b> · <b>Headroom for Teams</b> · Install · Proof · Agents · Docs · Discord · llms.txt

<sub><b>AI agents / LLMs:</b> read <code>/llms.txt</code> here, or fetch the live index · full docs blob.</sub>

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. Compression runs on your machine; no prompt or file content is sent anywhere to be compressed.

<sub>10,144 → 1,260 tokens. The same <code>FATAL</code> found.</sub>

What it does

  • Library — compress(messages) in Python or TypeScript, inline in any app.
  • Proxy — headroom proxy --port 8787, zero code changes, any language.
  • 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>.
  • MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client.
  • Cross-agent memory — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
  • `headroom learn` — mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md.
  • Output token reduction — trims what the model *writes back*, not only what you send. See below.
  • Reversible (CCR) — originals are cached locally and retrieved on demand.

How it works

text
 Your agent / app
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
        │   prompts · tool outputs · logs · RAG results · files
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (runs locally — your data stays here)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-v2-base (text, HF)  │
    │                                                    │
    │  Cross-agent memory  ·  headroom learn  ·  MCP     │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)
  • ContentRouter detects the content type and selects a compressor for it.
  • SmartCrusher / CodeCompressor / Kompress-v2-base handle JSON, source code and prose respectively.
  • CacheAligner flags volatile content that would bust a provider KV-cache prefix. It never rewrites prompts.
  • CCR stores originals locally so the model can call headroom_retrieve when it needs the full text.

→ Architecture · CCR · Kompress-v2-base model card

Get started (60 seconds)

bash
# 1 — Install
uv tool install --python 3.13 "headroom-ai[all]"  # CLI in a self-contained env
pip install "headroom-ai[all]"                    # Python — ships the `headroom` CLI
npm install headroom-ai                           # TypeScript SDK only — no CLI

# 2 — Pick a mode
headroom deploy                         # turnkey local deployment + agent config
headroom wrap claude                    # wrap a coding agent
headroom proxy --port 8787              # drop-in proxy, zero code changes
# or: from headroom import compress     # inline library

# 3 — Check it and watch the savings
headroom doctor                         # health check — confirms routing works
headroom perf
headroom dashboard                      # live savings (proxy must be running)

Inline, in Python:

python
from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

Excerpt — the full document is on GitHub.

More MCP & Tooling repositories

Catalog data refreshed . Something wrong? Report it.