headroom

A local-first context-compression toolkit for LLM agents (chopratejas, Apache-2.0, ~41k★, v0.26.0 Jun 2026): 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.

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

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