Headroom: Context Compression for AI Agents (Complete Guide)
Headroom by Tejas Chopra compresses tool outputs, logs, RAG chunks, and files before they reach the LLM—60–95% fewer tokens with reversible CCR. Library, proxy, MCP, wrap for Claude Code, Cursor, Codex, and benchmarks.
Headroom by Tejas Chopra is one of the fastest-growing open-source tools in agent infrastructure—29.5K+ GitHub stars, 2K forks, and 155 releases as of June 2026 (latest: v0.25.0). It is not another LLM wrapper. It is a local-first context compression layer that sits between your agent and the provider:
Compress everything your AI agent reads—tool outputs, logs, RAG chunks, files, conversation history—before it reaches the LLM. Same answers, fraction of the tokens.
Live demo from the README: 10,144 → 1,260 tokens—same FATAL found in a log search.
If Karpathy's LLM Wiki solves what knowledge to compile, Headroom solves how much of that knowledge fits in the window. They stack: a maintained wiki reduces re-retrieval; Headroom shrinks what still ships to the model.
Long sessions fill the window before the task finishes
Provider-native compaction (OpenAI, Anthropic /compact) helps conversation but not arbitrary tool payloads. Hosted compression APIs send your data off-machine and often destroy reversibility.
Headroom's pitch: compress at the boundary, locally, with retrieval on demand.
Headroom exchanges its GitHub OAuth token for Copilot's short-lived API token and sets COPILOT_PROVIDER_API_URL for the wrapper. Enterprise Server: set GITHUB_COPILOT_ENTERPRISE_DOMAIN. For Docker/CI, pass explicit GITHUB_COPILOT_TOKEN rather than relying on host keychain.
Agent Compatibility
Agent
headroom wrap
Notes
Claude Code
✅
--memory, --code-graph
Codex
✅
Shared memory with Claude
Cursor
✅
Config snippet to paste
Aider
✅
Starts proxy + launches
Copilot CLI
✅
Subscription mode supported
OpenClaw
✅
ContextEngine plugin
Any OpenAI-compatible client works via proxy. See Claude Code commands for /context and /compact alongside external compression.
Headroom vs Alternatives
Tool
Scope
Local
Reversible
Headroom
All context types
✅
✅ (CCR)
RTK
CLI command outputs
✅
❌
lean-ctx
CLI, MCP, editor rules
✅
❌
Compresr / Token Co.
Text via hosted API
❌
❌
OpenAI compaction
Conversation only
Provider
❌
Headroom ships RTK for shell-output rewriting and can use lean-ctx via HEADROOM_CONTEXT_TOOL=lean-ctx—compress downstream of whichever CLI context tool you prefer.
If pip install fails with CERTIFICATE_VERIFY_FAILED, install Rust first (maturin downloads rustup over TLS), or use prebuilt wheels: pip install --only-binary headroom-ai headroom-ai.
Headroom is the context compression layer the agent ecosystem was missing: local-first, multi-algorithm, reversible, and agent-native. 29.5K stars in roughly five months since OSS release reflects how universal the token problem is.
Install in 60 seconds. Wrap Claude Code in one command. Keep your data on your machine. Retrieve originals when the model needs them.
