Headroom comprime lo que lee tu agente de IA, antes de que llegue al modelo

Le pedís a Claude Code que revise por qué falla un endpoint. Va, corre los tests, y uno de ellos te devuelve un volcado de log de diez mil líneas. Ese log entero —con sus tres mil líneas repetidas de “conexión OK” y una sola línea de FATAL en el medio— entra al contexto del modelo. Vos solo necesitabas esa línea, pero pagaste por las diez mil.

Headroom (abre en una pestaña nueva) es una herramienta gratuita, de código abierto, que comprime eso antes de que llegue al modelo: salidas de herramientas, logs, resultados de búsqueda, archivos, el historial de la conversación. Corre en tu máquina —no manda tu código a ningún servidor para comprimirlo— y la promesa central es esa: la misma respuesta, con una fracción de los tokens.

Cómo funciona

No reescribe el texto con otro modelo de IA ni resume con IA generativa, que es lo primero que uno imagina y sería lento y poco confiable. Cada tipo de contenido tiene su propio compresor, elegido por reglas:

• SmartCrusher comprime JSON —arreglos y objetos anidados— con estadística, no con una lista de palabras clave: mira la varianza de cada campo y conserva los valores atípicos, los elementos con error, y el primero y el último de cada lista. Si tenés cien resultados de una búsqueda y noventa y cinco son casi idénticos, guarda los que importan y resume el resto.
• CodeCompressor entiende la sintaxis del código —Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, Perl— y conserva imports, firmas de función y tipos, que es la parte que un modelo necesita para entender qué hace un archivo sin leerlo entero.
• Kompress-v2-base es un modelo propio, publicado en HuggingFace (abre en una pestaña nueva) y entrenado específicamente con trazas de agentes, para el texto que no es ni JSON ni código: prosa, resultados de búsqueda, documentación.

CacheAligner no comprime nada: marca qué partes del texto son volátiles —cambian en cada pedido— para que no rompan el prefix caching que ya usa tu proveedor. Los proveedores de modelos cobran mucho menos por los tokens que ya vieron antes en el mismo lugar; si algo que cambia todo el tiempo queda al principio del prompt, ese descuento se pierde en cada llamada.

Los números, con la cuenta que los generó

Headroom publica cuatro escenarios armados con formatos reales de herramientas MCP, medidos con el tokenizador del proveedor. Se pueden reproducir con la misma semilla y te da los mismos números:

uv run python benchmarks/index_proof_table.py --seed 20260902

Escenario	Antes	Después	Ahorro
Búsqueda de código (100 resultados)	17.199	13.597	21%
Depuración de un incidente	55.957	24.340	57%
Explorar un repositorio	58.801	33.895	42%
Clasificar issues de GitHub	46.067	32.429	30%

El ahorro depende de cuánto se repite el contenido: un arreglo JSON con la misma forma en cada elemento, o un log con la misma línea mil veces, llega a más del 90% en las pruebas de los propios autores. Un texto ya denso —una respuesta corta, sin relleno— se comprime poco o nada. Comprimir en sí cuesta menos de un milisegundo: 0,21 ms sobre 10 mil tokens, 1,4 ms sobre 100 mil, así que no se nota en la latencia de una conversación normal.

Comprimido, pero no perdido

La parte que hace que esto sea seguro de usar es que nada se descarta. La sigla es CCR — Compress-Cache-Retrieve: comprimir, guardar en caché, poder recuperar. El original de cada dato que se comprime queda guardado en tu máquina, y si el modelo necesita el detalle exacto que se resumió, tiene una herramienta —headroom_retrieve— para pedirlo de vuelta.

Es la misma idea de fondo que ya usamos en este blog para los comentarios de los artículos: no se borra nada, se guarda y se puede volver a pedir cuando hace falta. Acá el que “pide de vuelta” no sos vos, es el propio modelo, cuando la respuesta comprimida no le alcanza para responder bien.

¿Cambia lo que contesta el modelo?

Es la pregunta obvia, y Headroom la responde con una tabla de precisión, no solo con una frase:

Prueba	Qué mide	Sin comprimir	Con Headroom	Diferencia
GSM8K	Matemática	0,870	0,870	±0,000
TruthfulQA	Precisión factual	0,530	0,560	+0,030
SQuAD v2	Responder preguntas	—	97%	con 19% de compresión
BFCL	Uso de herramientas	—	97%	con 32% de compresión

Con cien casos de prueba, una diferencia de ±0,03 cae dentro del margen de error normal: no significa que TruthfulQA mejoró, significa que no hay diferencia detectable. El resultado real es el mismo con y sin comprimir, en las cuatro pruebas.

Cómo probarlo

Se instala como paquete de Python o de Node, y se usa de tres maneras distintas según cuánto querés tocar tu proyecto:

# instalación
pip install "headroom-ai[all]"        # Python, trae la línea de comandos
npm install headroom-ai               # TypeScript, solo la librería

# la forma más simple: envolver el agente que ya usás
headroom wrap claude                  # también: codex, cursor, aider, opencode…

# sin instalar nada en tu proyecto: correrlo como proxy
headroom proxy --port 8787            # cualquier cliente compatible con OpenAI/Anthropic

# o dentro de tu propio código

from headroom import compress
from openai import OpenAI

mensajes = [{"role": "user", "content": "Analizá estos resultados"}]
resultado = compress(mensajes, model="gpt-4o")
respuesta = OpenAI().chat.completions.create(model="gpt-4o", messages=resultado.messages)
print(f"Ahorrados {resultado.tokens_saved} tokens ({resultado.compression_ratio:.0%})")

headroom wrap es la opción para quien solo quiere el ahorro sin cambiar nada del código: levanta un proxy local, configura el agente para pasar por él, y con headroom unwrap claude se deshace todo. También hay un servidor MCP (headroom_compress, headroom_retrieve, headroom_stats) para quien ya usa ese protocolo.

Un detalle de privacidad que vale la pena aclarar

La documentación de Headroom tiene, en dos lugares distintos, dos afirmaciones que se contradicen sobre si manda datos a algún lado por defecto. Como esto importa, fui al código en vez de quedarme con la documentación:

Hay dos interruptores separados, y confundirlos es fácil:

• HEADROOM_TELEMETRY — estadísticas que se guardan solo en tu máquina, para que el comando headroom stats tenga algo que mostrar. Viene apagado por defecto.
• HEADROOM_BEACON — un resumen anónimo de la sesión (nunca el contenido de tus prompts, ni tu código) que sí se sube a los servidores de Headroom Labs. Viene prendido por defecto: hay que apagarlo a propósito.

Se apaga con HEADROOM_BEACON=off, con la convención estándar DO_NOT_TRACK=1, o corriendo en modo --offline. Si te importa que nada salga de tu máquina —el mismo motivo por el que Headroom existe, en realidad—, conviene apagarlo antes de la primera vez que lo corras.

Cuándo conviene y cuándo no

Conviene si usás un agente de código todos los días y querés ahorrar tokens sin tocar tu proyecto, si trabajás con más de un agente (Claude Code y Codex, por ejemplo) y querés que compartan memoria, o si te importa poder recuperar el original de lo que se comprimió.

No aporta mucho si ya usás la compactación nativa de un solo proveedor y no necesitás nada más, o si trabajás en un entorno donde no podés correr un proceso local —un sandbox restringido, por ejemplo—. Tampoco ayuda en conversaciones cortas o con texto que ya viene denso: ahí no hay nada repetitivo que comprimir.

Es software libre, con licencia Apache 2.0, y el repositorio en sí es “Repositorio del día” (abre en una pestaña nueva) en Trendshift — señal de que no es un proyecto de nicho, sino algo que bastante gente ya está usando.