¿Qué es Headroom?
Headroom comprime lo que lee un agente de IA antes de que llegue al modelo: resultados de herramientas, registros, resultados de búsqueda, fragmentos de RAG, archivos e historial. Un enrutador detecta el tipo de contenido y pasa el JSON a un compresor estadístico, el código fuente a un compresor que entiende el AST y la prosa a Kompress-v2-base, un modelo pequeño que el equipo entrenó con trazas de agentes. Los originales se guardan en local para que el modelo pueda pedir el texto completo.
Se distribuye como librería de Python y TypeScript (`headroom-ai`), como proxy en el puerto 8787, como envoltorio de un solo comando para Claude Code, Codex, Copilot, Aider y unos 15 agentes más, y como servidor MCP. Entre los extras hay memoria compartida entre agentes, `headroom learn`, que revisa sesiones fallidas para escribir correcciones en `CLAUDE.md`, y un recortador de salida opcional. Headroom Labs vende una edición empresarial junto al código Apache 2.0.
¿Merece la pena Headroom?
El proyecto publica cifras reproducibles en lugar de un único número de reclamo. En cuatro escenarios con semilla fija, construidos con formatos reales de salida de MCP, redujo los tokens de entrada un 21 % en búsqueda de código, un 42 % en exploración de la base de código, un 30 % en triaje de issues y un 57 % en depuración de incidentes, y los arrays JSON y líneas de registro repetidos superan el 90 %. La prosa apenas se encoge. La compresión tarda 0,21 ms en la mediana sobre un resultado JSON de 10.000 tokens, así que no añade latencia apreciable, y en pequeñas pruebas de precisión (100 preguntas cada una) las puntuaciones se quedaron dentro del margen de error.
El uso independiente cuenta la misma historia con un énfasis menos favorable. El blog russ.cloud lo usó unos días en programación interactiva mixta y vio un 20,7 % menos de tokens sobre 1,9 millones, pero el ahorro en dinero del panel era sobre todo el descuento por caché de prompts del propio proveedor (47,36 $) y no la compresión (9,23 $), con 304 ms de sobrecarga del proxy por petición; su autor encontró `headroom learn` más útil que el compresor. Una segunda reseña confirmó que los recuentos de tokens coinciden con los del proveedor, pero dudó de que la factura baje siempre.
La adopción es real y no solo viral: 466.346 descargas en PyPI en el último mes y 125.494 en npm, frente a 79.667 estrellas y 3.730 commits. Las versiones son frecuentes; v0.44.0 salió el 10 de noviembre de 2026.
La pega: una baliza de telemetría anónima viene activada por defecto (ratios de compresión, ID de proveedor y modelo, sistema operativo; ni prompts ni código), y el proxy está en el camino de cada clave de API y cada petición. Se han publicado dos avisos, un secuestro de WebSocket entre sitios de gravedad alta en agosto y una lectura arbitraria de archivos en la herramienta de lectura del servidor MCP el 9 de noviembre de 2026, ambos corregidos.
Nuestra opinión: en un agente que lee grandes cargas JSON, registros o resultados de búsqueda, se paga solo; para la programación normal tipo chat, los filtros de comandos de RTK hacen buena parte del mismo trabajo con menos maquinaria.
Dónde se gana su sitio
Un equipo de SRE que usa Claude Code para depurar incidentes
Evitar que volcados de registros y JSON de métricas llenen la ventana de contexto
`headroom wrap claude` arranca un proxy local para la sesión; el escenario de incidentes del proyecto bajó de 55.957 a 24.340 tokens. El modelo puede recuperar las líneas originales con la herramienta de recuperación cuando las necesita.
Un desarrollador backend con una API de RAG en Python
Reducir el coste de entrada en listas largas de fragmentos recuperados y filas de base de datos
Llama a `compress(messages, model=...)` antes de la llamada al proveedor; se ejecuta en el propio proceso sin clave ni red. Antes ejecuta `headroom evals` con tu propio tráfico, como recomiendan los revisores, para confirmar que las respuestas no cambian.
Una ingeniera que corrige una y otra vez los mismos errores del agente
Convertir los fallos repetidos en instrucciones permanentes
`headroom learn` lee sesiones pasadas y escribe correcciones en `CLAUDE.local.md` o `AGENTS.md`; un probador independiente lo consideró la parte más útil. No cuesta nada aparte de la ejecución.
Antes de decidirte
- Puesta en marcha
- `uv tool install --python 3.13 "headroom-ai[all]"` y luego `headroom wrap claude` (o codex, copilot, aider y otros); `headroom doctor` comprueba el enrutamiento. Librerías: `pip install headroom-ai` o `npm install headroom-ai`.
- Integraciones
- Claude Code, Codex, Copilot CLI y VS Code, Cursor (manual), Aider, OpenCode, Cline, Continue, Goose, OpenHands y más; envoltorios para los SDK de Anthropic, OpenAI y Vercel AI; LiteLLM, LangChain, Agno y Strands; servidor MCP.
- Datos y privacidad
- La compresión se ejecuta en local y los originales se guardan en tu máquina. Una baliza anónima envía por defecto ratios, contadores, ID de proveedor y modelo, sistema operativo y arquitectura; `HEADROOM_TELEMETRY=off` o `DO_NOT_TRACK=1` la detiene.
- Coste a escala
- Sin coste de licencia. El ahorro crece con la repetición: un 90 % o más en JSON y registros repetidos, alrededor del 20 % en sesiones de programación mixta en una prueba independiente; la caché de prompts puede cubrir ya buena parte del ahorro en dinero.
- Límites
- La prosa y los prompts cortos apenas se comprimen; la CLI necesita Python; los proveedores de terceros compatibles con OpenAI necesitan una URL de destino explícita o la clave acaba en OpenAI; 302 issues abiertos.
Lo bueno
- Pruebas reproducibles con cifras honestas por escenario
- La compresión es local y reversible bajo demanda
- Librería, proxy, envoltorio de agentes y servidor MCP en un solo paquete
- Mucho uso real: 466.346 descargas en PyPI en un mes
Lo malo
- Poco ahorro en prosa y programación interactiva
- Baliza de telemetría activada por defecto
- El proxy maneja cada clave y petición; dos avisos desde agosto
- Funciones que se extienden más allá de la compresión
Ideal para
Equipos cuyos agentes o canalizaciones de RAG meten en el modelo mucho JSON, registros o resultados de búsqueda y pagan por token de entrada.
Alternativas a Headroom
Headroom: preguntas frecuentes
- ¿Merece la pena Headroom?
- Headroom es el más riguroso de los complementos para ahorrar tokens, y sus propias cifras muestran que el ahorro depende casi por completo de lo repetitiva que sea la salida de tus herramientas. Le damos un 3.9 sobre 5.
- ¿Cuánto cuesta Headroom?
- Gratuito y de código abierto (Apache 2.0). Headroom Enterprise para equipos se vende aparte; precio no publicado.
- ¿Qué inconvenientes tiene Headroom?
- Poco ahorro en prosa y programación interactiva; baliza de telemetría activada por defecto; el proxy maneja cada clave y petición; dos avisos desde agosto; funciones que se extienden más allá de la compresión.
- ¿Para quién es Headroom?
- Equipos cuyos agentes o canalizaciones de RAG meten en el modelo mucho JSON, registros o resultados de búsqueda y pagan por token de entrada.
- ¿Cuánto cuesta Headroom para un equipo o en producción?
- Sin coste de licencia. El ahorro crece con la repetición: un 90 % o más en JSON y registros repetidos, alrededor del 20 % en sesiones de programación mixta en una prueba independiente; la caché de prompts puede cubrir ya buena parte del ahorro en dinero.
- ¿Es Headroom seguro para los datos de la empresa?
- La compresión se ejecuta en local y los originales se guardan en tu máquina. Una baliza anónima envía por defecto ratios, contadores, ID de proveedor y modelo, sistema operativo y arquitectura; `HEADROOM_TELEMETRY=off` o `DO_NOT_TRACK=1` la detiene.
- ¿Cuáles son las mejores alternativas a Headroom?
- Las alternativas más cercanas que hemos analizado son rtk (Rust Token Killer), Caveman y OmniRoute.
Respuestas comprobadas el 14 nov 2026.