Headroom: Cómo Cortar Hasta 95% de tus Tokens Sin Cambiar las Respuestas
Cada tool call que hace tu agente, cada log que lee, cada RAG chunk y cada archivo que le metés al contexto: pagás por todo, y la mayor parte es boilerplate. Headroom es una capa open-source que se ubica entre tu agente y el modelo, y comprime todo antes de que llegue al LLM. La promesa es directa: las mismas respuestas, una fracción de los tokens.
El proyecto es de Tejas Chopra, un ingeniero de Netflix, y viene moviéndose rápido: ya es una de las herramientas para developers más estrelladas de este espacio. Es Apache 2.0, corre localmente (tus datos nunca salen de tu máquina) y es model-agnostic: Claude, Codex, Cursor, Aider, Copilot del lado del agente, y Anthropic, OpenAI, Bedrock, Vertex, Azure o más de 100 providers vía LiteLLM en el backend.
Qué hace, en concreto
Headroom intercepta lo voluminoso —tool outputs, logs, lecturas de base de datos, resultados de RAG, lecturas de archivos, historial de conversación— y lo pasa por un pipeline de compresores especializados antes de que llegue al modelo:
- SmartCrusher para JSON: conserva los primeros y últimos items, los errores, las anomalías y los matches de relevancia, y aplasta el medio repetitivo.
- CodeCompressor, AST-aware para Python, JS, Go, Rust, Java y C++.
- Kompress-base, el modelo propio del proyecto en HuggingFace, entrenado sobre agentic traces, para texto plano.
- Un ML router para compresión de imágenes.
La decisión de diseño clave es que la compresión es reversible. Headroom cachea los originales localmente (el sistema CCR — Compress-Cache-Retrieve) e inyecta una tool headroom_retrieve para que el modelo pueda recuperar los datos completos si decide que le falta algo. Ese es el mecanismo detrás de la promesa de “las mismas respuestas”: nada se descarta de forma permanente, simplemente se mantiene fuera del prompt hasta que hace falta.
Cuatro formas de meterlo en tu stack
Esta es la parte que hace que Headroom sea fácil de probar. No tenés que comprometerte con una arquitectura: elegí la integración que coincida con cómo ya trabajás.
Proxy (cero cambios de código). Lo arrancás y apuntás el base URL de tu agente hacia él:
pip install "headroom-ai[all]"
headroom proxy --port 8787
# Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude
# Cualquier cliente OpenAI
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
Agent wrap, un solo comando: headroom wrap claude|codex|cursor|aider|copilot.
Library, inline en Python o TypeScript:
from headroom import compress
result = compress(messages, model="claude-sonnet-4-5-20250929")
# result.messages: misma estructura, muchos menos tokens
MCP server, para cualquier MCP client: headroom mcp install expone headroom_compress, headroom_retrieve y headroom_stats como tools.
Los números, y de dónde salen
El titular de Headroom es 60–95% de reducción de tokens con la calidad de las respuestas preservada. Esos son los benchmarks propios del proyecto y, hay que reconocerlo, son reproducibles: clonás el repo y corrés vos mismo la suite de evals. Los más destacados: 94.9% de compresión con 98.2% de recall en un benchmark de extracción de artículos, y 76.3% de compresión en un test de agente multi-tool donde todos los hallazgos objetivo seguían recuperándose.
Lo que vale la pena marcar es cómo el proyecto maneja su feature de tokens de salida —recortar lo que el modelo escribe de vuelta, no solo lo que vos mandás—. En lugar de citar un porcentaje con falsa seguridad, el README es honesto en que ese ahorro no se puede observar directamente: reporta un estimado con un intervalo de confianza del 95% (por ejemplo ~32%, con un rango declarado) y ofrece una vía de medición real: dejá el 10% de tus conversaciones sin comprimir como grupo de control con HEADROOM_OUTPUT_HOLDOUT=0.1 y el dashboard etiqueta el número como measured en vez de estimated. Ese tipo de mesura en el propio README de un proyecto v0.x es buena señal.
Dónde no encaja
La compresión no es magia gratis, y el proyecto lo dice de frente. El texto denso y único, o el código novedoso, comprimen mucho menos: el propio benchmark de exploración de codebase de Headroom apenas llegó al 47%, porque sencillamente hay menos boilerplate que sacar. Y el round-trip de comprimir/recuperar agrega una pieza móvil: si el modelo abusa de headroom_retrieve, recuperás parte del ahorro de vuelta, así que vas a querer medir sobre tu propio tráfico en lugar de confiar en el número del titular.
Donde brilla es en el perfil opuesto: agentes que disparan muchas tools e ingieren outputs estructurados grandes (resultados de búsqueda, respuestas de API, log dumps), pipelines de RAG metiendo chunks repetitivos, y sesiones automatizadas de larga duración donde los mismos archivos e historial se reenvían turno tras turno.
Vale la pena probarlo
Es un proyecto v0.x moviéndose rápido, así que fijá una versión, leé el changelog y probá antes de producción. Pero la fricción para probarlo es realmente baja —un proxy y un cambio de base URL— y la premisa es sólida: en un montón de workflows de agentes el cuello de botella no es el modelo, es el volumen de contexto de bajo valor que estás pagando por mandarle. Headroom es un intento limpio y honesto de arreglar eso, de alguien que claramente piensa en costo a escala.
¿Ya estás midiendo cuántos tokens de tu pipeline son boilerplate, o todavía estás pagando la factura completa sin mirarla?