Headroom is a context compression layer for AI agents and LLM applications. It shrinks the text an agent sends to a model — tool outputs, logs, RAG chunks, files, and conversation history — to reduce token counts (and therefore cost and latency) while aiming to preserve the same answers. It ships as a Python library, a TypeScript/npm package, a drop-in HTTP proxy, and an MCP server.

The problem it addresses is the high cost and limited context window of LLM usage. Verbose JSON, repetitive logs, and large retrieved documents waste tokens. Headroom routes content to type-specific compressors (JSON crusher, AST-based code compressor, an ONNX text model) and keeps originals recoverable so nothing is permanently lost.

It targets developers and teams running coding agents (Claude Code, Cursor, Codex, Aider, Copilot) or LLM pipelines (LangChain, Agno, Strands). Usage ranges from inline `compress(messages)` calls, to running `headroom proxy` with zero code changes, to `headroom wrap <agent>` for one-command integration, plus MCP tools and cross-agent shared memory.

Architecturally it is a hybrid Python/Rust codebase. The original implementation is Python (FastAPI proxy, Click CLI, tiktoken, litellm, ONNX/transformers for the Kompress text model), and a Rust workspace (headroom-core, headroom-proxy, headroom-py PyO3 bindings, plus a parity harness) is being ported in for performance. The 'REALIGNMENT' docs describe an active, phased migration of hot paths from Python to Rust with byte-for-byte parity guarantees.

The codebase is unusually well-documented and disciplined: detailed engineering comments explaining serde feature choices, parity invariants, glibc-compat shims, and a dedicated Rust-vs-Python parity test crate. It uses Apache-2.0, has CI, codecov, release-please, pre-commit, and GitGuardian config. The notable tension is the dual Python/Rust implementation mid-migration, which adds complexity but appears deliberate and well-tracked.