headroom: Comprime todo lo que tu agente lee antes de mandarlo al modelo: 60 a 95% menos tokens, misma respuesta.

Comprime todo lo que tu agente lee antes de mandarlo al modelo: 60 a 95% menos tokens, misma respuesta.

Cada output de herramienta, log, archivo y chunk de RAG que tu agente manda al modelo se paga en tokens. Headroom los comprime en local antes de salir, y guarda el original por si el modelo necesita recuperarlo. La factura baja sin que cambies tu código.

Estrellas

26k★

Lenguaje

Python

Menos tokens

60-95%

Revisado

13 jun 2026

De un vistazo, lo que vas a obtener si lo instalas.

Sin tocar código

Modo proxy drop-in: prendes headroom en un puerto, apuntas tu agente ahí y comprime solo.

Compresión reversible

Guarda el original en local. Si el modelo necesita el detalle recortado, lo recupera con una herramienta.

Detecta el tipo

Compresores distintos para JSON, código (vía AST) y texto. No aplica la misma tijera a todo.

Cuatro modos

Librería, proxy, wrapper de agente o servidor MCP. Eliges según cómo ya trabajas.

Multi-agente

Memoria comprimida compartida entre varios agentes, donde más se acumula el desperdicio de tokens.

El contexto detrás del repo.

El costo de un agente no está en el prompt que escribes, está en todo lo que el agente lee para contestarte: salidas de herramientas, logs enormes, archivos completos, chunks de RAG, historial de conversación. Todo eso viaja al modelo en cada turno y todo eso se paga por token. En un agente de código que trabaja un día entero, ese desperdicio es la mayor parte de la cuenta.

Headroom se mete en medio. Detecta el tipo de contenido (JSON, código, texto), elige el compresor adecuado y recorta antes de mandar al modelo. Los benchmarks del repo sobre cargas reales de agente: 92% menos tokens en búsqueda de código (de 17,765 a 1,408), 92% en debugging de incidentes SRE (de 65,694 a 5,118), 73% en triage de issues de GitHub, 47% en exploración de codebase. En pruebas de exactitud (GSM8K, TruthfulQA, SQuAD v2, BFCL) reporta las mismas respuestas con 19 a 32% de compresión adicional.

Lo que lo hace usable es que no te obliga a reescribir nada. Corre como librería (`compress(messages)`), como proxy drop-in (`headroom proxy`), envolviendo tu agente directo (`headroom wrap claude`) o como servidor MCP. Y guarda el contenido original en local: si el modelo necesita el detalle que se comprimió, lo recupera con una herramienta (`headroom_retrieve`). Compresión reversible, no destructiva.

Cuándo lo recomiendo (y cuándo no).

Lo recomiendo para quien corre agentes de código (Claude Code, Cursor, Aider, Codex) todo el día sobre repos grandes y siente la factura mensual subir. El modo proxy es la entrada más barata: lo prendes en un puerto, apuntas tu agente ahí y ya estás comprimiendo sin tocar código. Para flujos multi-agente, la memoria compartida comprimida entre agentes es donde más se nota el ahorro.

No es para ti si usas un solo proveedor y ya te sirve su compresión nativa sin necesidad de compartir contexto entre agentes, o si tu entorno no puede correr procesos locales (porque Headroom procesa en tu máquina, no en la nube). En esos casos la capa extra estorba más de lo que ayuda.

En 3 pasos, listo para probar.

Instala el paquete

pip install "headroom-ai[all]"

Requiere Python 3.10 o más. También hay paquete de npm (headroom-ai) e imagen de Docker en ghcr.io/chopratejas/headroom.

Elige modo

# Envolver el agente
headroom wrap claude

# O proxy drop-in
headroom proxy --port 8787

El proxy es la entrada sin código: apuntas tu agente al puerto 8787 y comprime todo lo que pasa. wrap claude lo integra directo en Claude Code.

Mide el ahorro

headroom perf

Te muestra cuántos tokens estás recortando en tu carga real, para saber si vale la pena dejarlo prendido.

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.