headroomlabs-ai / 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
 [code] 
- **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)
 [code] 
Inline, in Python:
 [code] 
Launch a wrapped agent session each time, so the setup runs. `headroom wrap`
starts a local proxy, installs **Serena** for
semantic code navigation, and launches the agent configured to route through
Headroom. For Claude Code, Serena is registered for the wrapped project only
(as a `local`-scope MCP server in `~/.claude.json`). Use
`--code-memory-scope user` to make it available in every project, or
`--code-memory none` to skip it. `headroom unwrap` removes either registration.
The `headroom` CLI ships only in the PyPI package. The npm `headroom-ai` package
is the TypeScript SDK — a library you import
(`import { compress } from 'headroom-ai'`) — and provides no `headroom` command.
## Proof
Four scenarios built from real MCP server output formats, measured with the
provider tokenizer and the shipped `compress()`. Seeded and offline, so you get
the same numbers we did:
 [code] 
| Scenario | Before | After | Saved |
|---|---:|---:|---:|
| Code search (100 results) | 17,199 | 13,597 | **21%** |
| SRE incident debugging | 55,957 | 2