README

Quickstart ·
  Headroom for Teams ·
  Install ·
  Proof ·
  Agents ·
  Docs ·
  Discord ·
  llms.txt


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





Headroom (headroom-ai on PyPI and npm) compresses everything your AI agent
reads — tool outputs, logs, RAG chunks, files, and conversation history — before
it reaches the LLM. Same answers, fewer input tokens. Measured: 21–57% fewer
input tokens on four agent scenarios, 90%+ on repeated JSON arrays and log
lines, little on prose (Proof). Compression
runs on your machine; no prompt or file content is sent anywhere to be compressed.

 Start here

My app calls an LLM (Python, LangChain, LiteLLM, Agno, Strands):

bash
pip install headroom-ai


python
from headroom import compress

result = compress(messages, model="gpt-4o")   OpenAI or Anthropic message dicts
client.chat.completions.create(model="gpt-4o", messages=result.messages)


No API key, no model download, in-process. Set HEADROOM_OFFLINE=1 for a
zero-network run. Tool and assistant messages are compressed; user messages are
left alone unless you pass compress_user_messages=True.
FastAPI example ·
API reference.
TypeScript apps: npm install headroom-ai plus the proxy
(pip install "headroom-ai[proxy]", headroom proxy --port 8787); the npm SDK
sends messages to it. TypeScript quickstart

I run coding agents (Claude Code, Codex, Cursor, Copilot, OpenCode, Aider):

bash
uv tool install --python 3.13 "headroom-ai[all]"
headroom wrap claude


Zero code changes. Agent compatibility ·
Proxy


  



  
  10,144 → 1,260 tokens. The same FATAL found.


 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|droid|zcode in one command; undo with headroom unwrap .
- 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


 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)         │
   

Top issues

Discussions

Latest release

0.43.1 (2026-11-05)


 Bug Fixes

 ccr: keep the in-memory order queue from evicting re-stored entries (4545) (c6f5bf9)
 memory: read the relation key the memory_save schema advertises (4647) (7592e68)
 memory: replace the HNSW vector when a memory is re-indexed (4649) (ee638f9)
 openclaw: accept 12-character hashes in headroom_retrieve (4640) (8d3e9e5)
 ort: avoid implicit runtime discovery from the workspace (4570) (69fbd23)
 proxy: bound the model-keyed tokenizer, beacon and litellm caches (4497) (e51b806)
 proxy: use HTTP/1.1 client for ChatGPT streaming and model metadata (4006) (e1becdf)