headroom

A local-first context-compression toolkit for LLM agents (Apache-2.0): it compresses everything an agent reads — tool outputs, logs, files, RAG chunks, conversation history — before it reaches the model, claiming 60–95% fewer tokens at the same answer quality. The demand-side answer to the token-cost problem the spoke tracks from the supply side (anthropic-agent-sdk-billing-pause): vendors meter tokens; headroom cuts the tokens.

Re-verified 2026-08-20 (quality cycle). The repository moved: chopratejas/headroom now redirects to headroomlabs-ai/headroom, so what this page recorded as one developer's project in June is a company two months later. The figures moved with it — 66,987★ against the ~41k recorded here, 5,160 forks, 508 open issues, and a push on the day of the check. The stated compression range in the description has also changed shape: "20% fewer tokens for coding agents, 60–95% fewer tokens for JSON", where the June page carried the 60–95% figure without the workload split. The headline number now applies to the structured case and coding agents are claimed a fifth, which is a more modest and more checkable claim than the one this page has been repeating.

How it works — content-typed compressors

A ContentRouter detects content type and dispatches to a specialized compressor:

SmartCrusher — universal JSON (arrays/nested/mixed).
CodeCompressor — AST-aware for Python/JS/Go/Rust/Java/C++.
Kompress-base — a custom HuggingFace model trained on agentic traces for prose.
CacheAligner — stabilizes prompt prefixes to maximize provider KV-cache hits (a direct tie to prompt-caching economics; cf. llm-inference / llm-providers cost threads, cross-spoke).
CCR (reversible compression) — caches originals locally so the LLM can retrieve on demand (TTL'd) — compression without permanent information loss.

How you run it

Four surfaces: library (compress() in Python/TS), drop-in proxy (localhost:8787, zero code change), CLI wrapper (headroom wrap claude / aider), and an MCP server (headroom_compress / headroom_retrieve / headroom_stats). Integrates the Anthropic/OpenAI SDKs, LiteLLM, LangChain, Vercel AI, etc.; compatible with coding agents (Claude Code, Codex, Cursor, Aider, OpenClaw).

Why it matters here

Two threads converge:

Agent memory / context — headroom ships cross-agent shared memory (one compressed store across Claude/Codex/Gemini with auto-dedup), and headroom learn mines failed sessions into agent-specific corrections — an memory + self-improvement play, not just a compressor.
The token-economics flip side — where anthropic-agent-sdk-billing-pause is the vendor metering the wrapper, headroom is the wrapper minimizing what's metered; "context engineering" as a cost lever.

Tier

Graded T1 at ingest, superseded 2026-08-20 → T3 — first-party repo (Apache-2.0, active: 156+ releases). freshness: volatile. Weakness recorded: the 60–95% and accuracy-parity numbers (GSM8K/TruthfulQA/SQuAD/BFCL "negligible or positive deltas") are self-reported benchmarks, not independently verified.

Sibling in the corner

pxpipe shares the goal — a drop-in proxy that cuts tokens before the model — but by modality arbitrage (render text as images to exploit vision-token pricing) rather than text compression, and it's irreversibly lossy where headroom's CCR keeps originals retrievable. Same "cut the tokens" corner, opposite reliability profile.

pxpipe · agent-memory · model-context-protocol · agentic-coding-harness · self-improving-agents · retrieval-augmented-generation · anthropic-agent-sdk-billing-pause · synthesis

Re-tiered 2026-08-20 → T3. Under the corpus rule adopted this day (../QUALITY.md → tier by the claim, not the URL), this page rests on the compression claim, which is why the page is in the wiki at all. It is also the claim that moved: the 2026-08-20 re-read found the range split by workload (20% for coding agents, 60–95% for JSON) where this page had carried the 60–95% figure flat. The artifact facts on this page remain first-party and checkable; the grade follows the claim the page is here for.