Headroom

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 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.

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

- 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…