Qué resuelve
Cuando pagas un agente de IA por token, la trampa es que el costo no está en lo que tú escribes. Está en todo lo que el agente lee para contestarte: la salida de cada herramienta, los logs que revisa, los archivos que abre, los chunks que saca de tu RAG, el historial entero de la conversación. En cada turno todo eso viaja al modelo y se cobra. En un agente de código que trabaja horas seguidas, ese tráfico es la mayor parte de la factura.
Headroom se planta entre tu agente y el modelo, y comprime ese tráfico antes de que salga. Lo importante: lo hace sin perder la respuesta. Guarda el original en local y deja que el modelo lo recupere si llega a necesitar el detalle.
Los números
El repo publica benchmarks sobre cargas reales de agente, no sintéticas:
| Carga de trabajo | Antes | Después | Ahorro |
|---|---|---|---|
| Búsqueda de código (100 resultados) | 17,765 | 1,408 | 92% |
| Debugging de incidente SRE | 65,694 | 5,118 | 92% |
| Triage de issue de GitHub | 54,174 | 14,761 | 73% |
| Exploración de codebase | 78,502 | 41,254 | 47% |
El rango general que declara es 60 a 95% menos tokens. En pruebas de exactitud (GSM8K para matemáticas, TruthfulQA para factual, SQuAD v2 para QA, BFCL para herramientas) reporta las mismas respuestas con 19 a 32% de compresión adicional.
La ganancia depende del tipo de carga: cuanto más repetitivo y estructurado es lo que el agente lee (resultados de búsqueda, logs), más recorta. La exploración de codebase, donde cada archivo aporta señal distinta, es donde el margen se acorta.
Cómo funciona bajo el capó
El pipeline detecta primero qué tipo de contenido entra y enruta a un compresor específico:
- SmartCrusher para JSON.
- CodeCompressor que entiende código vía AST, no como texto plano.
- Kompress-base para texto general.
- CacheAligner que estabiliza los prefijos para pegarle al KV cache del modelo.
- CCR (compresión reversible) que guarda los originales y deja que el modelo los pida con
headroom_retrieve.
Esa última pieza es la que separa a Headroom de un truncador tonto. No tira información, la guarda fuera del contexto y la trae de vuelta solo si hace falta.
Los cuatro modos
| Modo | Cómo se usa | Para quién |
|---|---|---|
| Librería | from headroom import compress |
Quien controla el código y quiere comprimir mensajes a mano |
| Proxy | headroom proxy --port 8787 |
Quien no quiere tocar código: drop-in |
| Wrapper | headroom wrap claude |
Integración directa con Claude, Codex, Cursor, Aider, Copilot |
| MCP server | Protocolo MCP nativo | Clientes que ya hablan MCP |
Funciona con apps de Python y TypeScript, los SDKs de Anthropic y OpenAI, Vercel AI SDK, LiteLLM, LangChain, Agno y middleware ASGI.
Limitaciones honestas
- Procesa en local. Si tu entorno no puede correr procesos locales (algún CI restringido, sandbox cerrado), no aplica.
- Si usas un solo proveedor y su compresión nativa ya te basta, sin necesidad de compartir contexto entre agentes, la capa extra estorba.
- La licencia es Apache 2.0 y el proyecto es nuevo (26k stars en pocos meses). El autor mantiene activo, pero no es código de cinco años en producción.
Mi recomendación
Si corres un agente de código todo el día y la factura mensual ya te incomoda, el modo proxy te deja medir el ahorro sin compromiso: lo prendes, apuntas el agente, corres headroom perf y ves cuánto recorta en tu carga real. Si los números se parecen a los del benchmark, lo dejas prendido. El downside es bajo porque la compresión es reversible y el original queda guardado en local. Para flujos multi-agente, donde el contexto compartido es lo que más infla la cuenta, es donde más vale la pena.