StackMap
Subscribe
Explore / headroom
headroomlabs-ai

headroom

Context compression layer for agents: squeezes tool outputs, logs, files and RAG chunks 20-95% before the LLM — reversible, local-first; library, proxy, one-command agent wrap, or MCP.

60,547 4,536 Python Apache-2.0updated today
codinggateway
View on GitHubDispute this mapping →
Curator's take

The dedicated answer to context bloat: content-aware compressors route JSON, logs and code differently (60-95% on JSON, 15-20% on real coding sessions), originals stay cached so the model can retrieve what compression dropped — the reversibility is what makes aggressive ratios safe. Adoption cost is near zero: `headroom wrap claude` and you're running, or use it as proxy/library/MCP. Prompt-cache-aware alignment avoids torching your cache hit rate. NOT free lunch: a lossy-in-context layer between agent and model is another thing to debug when the model 'misses' something — budget for retrieval round-trips — and the 20% coding figure is the honest number, not the 95% headline.

Mapped by ShipWithAI editors · links verified
README.md
  ██╗  ██╗███████╗ █████╗ ██████╗ ██████╗  ██████╗  ██████╗ ███╗   ███╗
  ██║  ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
  ███████║█████╗  ███████║██║  ██║██████╔╝██║   ██║██║   ██║██╔████╔██║
  ██╔══██║██╔══╝  ██╔══██║██║  ██║██╔══██╗██║   ██║██║   ██║██║╚██╔╝██║
  ██║  ██║███████╗██║  ██║██████╔╝██║  ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║
  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝
              The context compression layer for AI agents

60–95% fewer tokens (for JSON data), 15-20% fewer tokens (for coding agents) · library · proxy · MCP · content-aware compressors · local-first · reversible

CI codecov PyPI npm Model: Kompress-v2-base License: Apache 2.0 Docs

Docs · Install · Proof · Agents · Discord · llms.txt

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

chopratejas%2Fheadroom | Trendshift

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.

Headroom in action
Live: 10,144 → 1,260 tokens — 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 <tool>
  • MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client
  • Cross-agent memory — shared store across Claude, Codex, Gemini, Grok, auto-dedup
  • headroom learn — mines failed sessions, writes corrections to CLAUDE.local.md (default, gitignored) or CLAUDE.md / AGENTS.md / GEMINI.md / GROK.md
  • 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.
  • Reversible (CCR) — originals

Continue your stack

What teams reach for next — and why each earns a place beside headroom. Ranked by curator confidence.