🗜️headroom
headroomlabs-ai/headroom · homepage ↗
Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
⭐ Hugely popular: 66k stars, gaining about 1k a week
View on GitHub ↗repo profile
momentum
durability
bus factor = how many people it takes to cover more than half the commits (6 months). 1 is a solo project; higher means the work is spread across a team. top-author share is the single busiest author's slice of those commits.
since we covered it
why it's a big deal
- Cuts the tokens sent to an LLM by compressing tool outputs, logs, files, RAG chunks, and conversation history, with reported real-workload savings of 47 to 92 percent.
- Helps agent builders and CLI users lower context cost without rewriting code, via a library call, a drop-in proxy on port 8787, or an MCP server exposing compress, retrieve, and stats.
- Compression is reversible and local-first; originals stay on the user's machine and the model can pull them back through headroom_retrieve when needed.
under the hood
- Content passes through a CacheAligner, then a ContentRouter, then reversible compression, with the router picking a compressor per content type: SmartCrusher for JSON, an AST-aware CodeCompressor for several languages, and a HuggingFace model for general text.
- Primarily Python at 80 percent with a Rust component at 15 percent; requires Python 3.10 or newer and ships on PyPI, npm, and a GHCR Docker image under Apache 2.0.
- Integrates with Anthropic, OpenAI, Vercel AI SDK, LiteLLM, LangChain, Agno, and ASGI apps, and includes tested wrapping for agents such as Claude Code, Codex, Aider, Cline, and Continue.
Radar summary, generated from the project's public sources
star history
- PR#35 6k 2026-06-03
- now 66k + 61k since first covered
curve is sampled from GitHub's star history, plus our own daily readings since we covered it; the dashed stretch is before we first covered it, the solid line since. figures at coverage are the numbers we printed then (approx.), current count is live.
understory
Quietly building: more output than attention, for now.
- output, commits & releases
- clout, star velocity
output = commits & releases; clout = star velocity, both 0 to 100 monthly indices; the gap where output runs above clout is the understory. The understory →
covered in
-
Context compression before tokens ever reach the model
similar projects
compare these →- 🌊 SurfSense
leaner, 16k stars
Open-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9
16k ACTIVE - 🦌 DeerFlow
An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.
80k ACTIVE - 🧠 LangGraph
Build resilient agents.
40k ACTIVE
comments
Sign in with GitHub to add your blip on headroom.