Headroom: ahorra tokens en Claude Code, Codex y Cursor

Tu agente consume tokens por todo lo que lee. Logs repetidos, JSON enorme y archivos leídos varias veces llenan el contexto aunque la respuesta esté en una sola línea. Headroom comprime ese material en tu ordenador antes de enviarlo al modelo. Guarda los originales en caché local y el agente puede recuperar el texto completo con headroom_retrieve. Tejas Chopra, exingeniero de Netflix, lo creó como proyecto personal; Netflix no lo hizo.

Qué demuestran las cifras

El 30/09/2026 el repositorio tenía 74.123 estrellas y licencia Apache 2.0. El README describe una prueba de su equipo donde un log bajó de 10.144 a 1.260 tokens, unas 8 veces menos, y se encontró el mismo FATAL. El GIF junto al texto muestra una sesión de Claude Code, no esa prueba del log. Otro ejemplo de la imagen principal reduce 55.957 a 24.340 tokens (57%); la línea FATAL del elemento 67 queda intacta, byte a byte.

La tabla Proof del README informa de 21% (búsqueda de código), 57% (incidente SRE), 42% (exploración del código) y 30% (clasificación de incidencias) menos tokens de entrada en cuatro escenarios sintéticos de agentes, a 30/09/2026. No son facturas medidas. La caché, el precio del modelo y los tokens de salida cambian el coste final. Con una suscripción fija de Claude o ChatGPT, puedes ampliar tu margen de uso, no reducir tu cuota mensual. Las charlas cortas, la prosa y los datos ya densos apenas se comprimen.

uv tool install --python 3.13 "headroom-ai[all]"

pip install "headroom-ai[all]"

headroom wrap claude

headroom wrap codex

headroom wrap cursor

5

Verifica y mide

Con el proxy activo, en otra terminal:

TerminalCopiar

headroom doctor

TerminalCopiar

headroom dashboard

TerminalCopiar

headroom savings

El panel está en http://localhost:8787/dashboard. Ejecuta una tarea real con muchas salidas de herramientas y compara los tokens antes y después. Un panel vacío no demuestra ahorro.

Para otro cliente, ejecuta headroom proxy --port 8787 y configura ANTHROPIC_BASE_URL=http://localhost:8787 o OPENAI_BASE_URL=http://localhost:8787/v1 en su entorno. Para clientes MCP, headroom mcp install registra el servidor en los agentes detectados; --agent claude lo limita a Claude. Conserva las credenciales habituales de tu proveedor.

Privacidad y precio

La compresión es local: tus archivos y prompts no van a servidores de Headroom Labs para comprimirse. El prompt comprimido sí llega al proveedor de IA que ya utilizas. Según el README, un beacon anónimo está activo por defecto: envía ratios y contadores, nunca prompts, código ni rutas de archivos. Desactívalo con HEADROOM_BEACON=off, DO_NOT_TRACK=1 o --offline. El modelo Kompress puede descargarse de Hugging Face en el primer uso. Lee su política de confianza.

Todo el repositorio es gratis y Apache 2.0. La oferta de pago consiste en despliegue y soporte gestionados para equipos, con SSO, paneles de organización y VPC. No hay precios públicos.

Preguntas frecuentes

¿De verdad es gratis? Sí, el uso local del repositorio es gratuito. Tu proveedor de IA puede cobrar aparte.

¿Cambia las respuestas? Puede cambiarlas; no hay garantía de identidad en todas las tareas. En su prueba GSM8K, la precisión fue 0,870 → 0,870 con 100 preguntas. Eso no prueba equivalencia universal. Comprueba los resultados importantes y recupera el original cuando sea necesario.

¿Funciona con mi suscripción Claude o ChatGPT? Claude Code y Codex tienen integraciones documentadas. El acceso por suscripción, inicio de sesión y límites dependen del cliente y proveedor. ChatGPT en el navegador no permite configurar este proxy. Una cuota mensual fija no baja automáticamente.

¿Mi código va a Headroom Labs? No para comprimirse. El contenido restante sí va al proveedor LLM que configuraste.

¿Es headroom.js? No. headroom.js oculta la cabecera de una web al desplazarte.