Más de 76.000 estrellas en GitHub y en el Trending diario el 20 de octubre de 2026: Headroom llega con una promesa muy concreta para quien paga tokens de agentes. Comprime lo que el agente lee (salidas de herramientas, logs, fragmentos de RAG, ficheros e historial) antes de enviarlo al modelo, y lo hace en tu máquina. En su prueba más vistosa, un log de 10.144 tokens queda en 1.260 y el modelo sigue encontrando el mismo FATAL.
Qué es y cómo funciona
Headroom es una capa local que se pone entre tu agente o aplicación y el proveedor del modelo (Anthropic, OpenAI, Bedrock…). Se puede usar de cuatro formas: como librería (compress(messages) en Python o TypeScript), como proxy compatible con las APIs de OpenAI y Anthropic, envolviendo un agente de código con headroom wrap o como servidor MCP.
Por dentro, un ContentRouter detecta el tipo de contenido y elige compresor: SmartCrusher para JSON (conserva los errores, los valores atípicos y los extremos de cada lista), CodeCompressor con análisis del AST para Python, Go, Java, Rust y otros lenguajes, y un modelo propio publicado en Hugging Face, Kompress-v2-base, para la prosa. Dos piezas marcan la diferencia frente a un simple recorte:
- CCR (compresión reversible): guarda los originales en local y le da al modelo una herramienta
headroom_retrievepara pedir el texto completo cuando lo necesita. - Compresión solo de la zona viva: comprime lo nuevo (la última salida de herramienta, el último turno) y deja el prefijo intacto, para no romper la caché de prompts del proveedor.
Además trae memoria compartida entre agentes, headroom learn (analiza sesiones fallidas y escribe correcciones en CLAUDE.local.md u otros ficheros de instrucciones) y una reducción de tokens de salida, desactivada por defecto, que pide respuestas más escuetas y baja el esfuerzo de razonamiento en turnos rutinarios. El núcleo combina Python y Rust, con SDK de TypeScript, y la licencia es Apache-2.0.
Cómo se usa
La vía recomendada en el README para la CLI es uv; también hay imagen Docker:
uv tool install --python 3.13 "headroom-ai[all]"
headroom doctor # comprueba que el enrutado funciona
headroom proxy --port 8787 # proxy sin tocar código
headroom wrap claude # o envolver un agente de código
headroom dashboard # ahorro en vivoSi prefieres integrarlo en tu código, el ejemplo mínimo es pasar los mensajes por compress() antes de llamar al cliente:
from headroom import compress
from openai import OpenAI
messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")
client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")Dos avisos antes de lanzarlo. headroom wrap no es inocuo: arranca un proxy local, instala Serena como servidor MCP y, en Claude Code, lo registra en ~/.claude.json (se deshace con headroom unwrap). Y si usas un proveedor compatible con OpenAI que no sea OpenAI, como DeepSeek u OpenRouter, hay que pasar --openai-api-url; si no, el README avisa de que tu clave se envía a la API de OpenAI y te devuelve un 401.
Lo que me convence y lo que no
Me convence que publica cómo medir. Sus cuatro escenarios con formatos reales de servidores MCP se reproducen con una semilla fija, y los números son modestos y creíbles: 57 % de ahorro en depuración de un incidente de SRE, 42 % explorando un repositorio, 30 % triando issues y 21 % en búsqueda de código. La compresión cuesta 0,21 ms de mediana sobre un resultado JSON de 10.000 tokens. En precisión, el propio README admite que con 100 muestras la mejora en TruthfulQA está dentro del intervalo de confianza. Y el ritmo es altísimo: 3.316 commits, 203 versiones en PyPI desde enero de 2026 y la 0.41.0 publicada el 14 de octubre de 2026.
Lo que no: ese ritmo también es un riesgo. Sigue en 0.x, tiene 259 issues abiertos y la superficie es enorme (proxy, memoria, aprendizaje, enrutado de esfuerzo, autenticación de Copilot). El propio README reconoce que la prosa y las salidas ya densas apenas se comprimen, que los wheels nativos no cubren Intel macOS y que, en redes con inspección TLS, la instalación desde código fuente puede acabar pidiendo un curl … | sh de rustup. Y meter un proxy entre tu agente y el proveedor añade un componente más que mantener y que, en el modo wrap, maneja tus credenciales.
Headroom frente a LLMLingua
La referencia para comprimir prompts es LLMLingua, de Microsoft Research, que usa un modelo de lenguaje pequeño para eliminar los tokens poco informativos.
| Headroom | LLMLingua | |
|---|---|---|
| Enfoque | Compresor por tipo de contenido (JSON, código, prosa), reversible | Modelo pequeño que elimina tokens prescindibles |
| Despliegue | Librería, proxy, wrap de agentes, MCP, Docker | Librería de Python; integraciones con LangChain y LlamaIndex |
| Pensado para | Sesiones largas de agentes con mucha salida de herramientas | Prompts largos, RAG y contexto en general |
| Licencia | Apache-2.0 | MIT |
| Madurez | 0.41.0 (14/10/2026), desarrollo muy activo | 0.2.2 (abril de 2024), respaldo de artículos académicos |
Cuándo usar cada uno: LLMLingua encaja si tienes un pipeline de RAG en Python y quieres una técnica estudiada que comprime texto hasta 20 veces según sus autores. Headroom tiene más sentido si el gasto viene de agentes de código que leen JSON, logs y ficheros, porque entiende esos formatos, no rompe la caché del proveedor y permite recuperar el original. Yo lo probaría primero en modo proxy sobre un entorno de pruebas y con headroom savings sobre tráfico real antes de envolver el agente de todo el equipo.
Fuentes
- headroomlabs-ai/headroom (GitHub)
- headroom-ai en PyPI (PyPI)
- microsoft/LLMLingua (GitHub)