Programación y vibe coding
Ahorrar tokens en Claude Code y Cursor con Headroom: comprime lo que tu agente manda al modelo
Headroom se pone entre tu agente de código y el modelo y comprime en tu equipo JSON, logs y resultados de búsqueda antes de enviarlos. En sus pruebas ahorra de 21% a 57% de tokens. Se instala con pip y se activa con headroom wrap claude. Gratis y open source. No probado por Fluye.
| Herramientas | Claude Code (principal)Cursor |
|---|---|
| Qué necesitas |
|
| Coste aprox. | Headroom es gratis y open source (Apache-2.0). Pagas el agente y el modelo como siempre. Hay una versión de pago para equipos que no hace falta para uso individual. |
| Tiempo de montaje | 30 min (primera vez) |
| Nivel | Media |
| Plan gratis | Puede bastar para pruebas |
Prompt listo para usar
Acabo de instalar Headroom en este proyecto con headroom wrap [AGENTE]. Antes de seguir con la tarea: 1. Dime qué ha cambiado en la configuración de [AGENTE] y en este proyecto (proxy, servidores MCP, archivos nuevos). 2. Ejecuta headroom doctor y resume si algo falla. 3. Haz la tarea: [TAREA]. 4. Al acabar, ejecuta headroom savings y dime cuántos tokens se han ahorrado en esta sesión. Si una respuesta te parece incompleta porque falta contexto, recupera el original con headroom_retrieve en vez de inventar.
| Variable | Qué poner | Ejemplo |
|---|---|---|
[AGENTE] | El agente que has envuelto con Headroom | claude |
[TAREA] | Una tarea con mucha salida de herramientas, que es donde se ahorra | revisar los logs del último fallo en producción y proponer el arreglo |
Pégalo en: Claude Code, Cursor
Prompt propio de Fluye para comprobar el ahorro en tu caso. Los comandos son los del README de Headroom; no los hemos ejecutado aquí.
Cómo funciona
- Instala Headroom. Con pip install "headroom-ai[all]" o, mejor en Mac, uv tool install --python 3.13 "headroom-ai[all]". El comando headroom solo viene en el paquete de PyPI; el paquete de npm es una librería sin comando.
- Envuelve tu agente. headroom wrap claude arranca un proxy local y lanza Claude Code pasando por él. Sirve igual con codex, cursor, goose, openclaw y otros. Para quitarlo, headroom unwrap claude.
- Revisa lo que instala. wrap también instala Serena, un servidor MCP para navegar el código, registrado solo para ese proyecto en ~/.claude.json. Si no lo quieres, añade --code-memory none.
- Apaga la telemetría si quieres. Un aviso anónimo va activado por defecto: manda ratios, contadores, proveedor y modelo, nunca prompts ni código. Se desactiva con HEADROOM_TELEMETRY=off o DO_NOT_TRACK=1.
- Mide tu ahorro real. headroom savings te dice lo que ahorras con tu propio tráfico y headroom dashboard lo enseña en pantalla. Ese número vale más que el del titular.
Qué resultado esperar
Tu agente de código manda menos tokens al modelo en sesiones largas con JSON, logs y resultados de búsqueda, con los originales guardados en tu equipo por si el modelo los pide.
- Qué se hizo
- Un proyecto open source se pone entre el agente de código y el modelo y comprime en local lo que el agente manda: JSON, código, logs y resultados de búsqueda.
- Cómo fue
- En las cuatro pruebas publicadas en su README el ahorro va de 21% a 57% de tokens. El 95% del post solo se da con JSON muy repetitivo.
- A tener en cuenta
- Toca la configuración del agente y lleva telemetría anónima activada por defecto. Sin prueba propia todavía.
Límites y precauciones
- El ahorro depende de lo repetitivo que sea el contenido. En las pruebas del README va de 21% (búsqueda de código) a 57% (depurar un incidente). El 95% del post solo aplica a JSON muy repetitivo.
- La conversación normal, la prosa y la salida ya compacta apenas se comprimen.
- Si pagas un plan de suscripción y no por tokens, no hemos comprobado cómo afecta a tus límites de uso.
- Sin prueba propia todavía.
- wrap toca la configuración de tu agente y añade un servidor MCP. Prueba primero en un proyecto que no sea crítico y deshazlo con headroom unwrap si algo falla.
- Comprime en tu equipo, pero tus peticiones siguen yendo al proveedor del modelo como antes. No cambia lo que el proveedor ve de tu código.
- No lo uses en un entorno donde no puedas correr procesos locales: el propio README dice que ahí no compensa.
Variantes
Fuentes: repo Headroom en GitHub y el post de @liambraus en X (25 oct 2026). Caso curado, no probado por Fluye.
«el token más barato es el que nunca envías.» @liambraus, en su post en X.
Si usas Claude Code o Cursor por API, gran parte de lo que pagas no lo escribes tú: son los resultados de búsquedas, los logs y los JSON que el agente pega en la conversación. Headroom se pone en medio. Arranca un proxy en tu equipo, comprime cada tipo de contenido con su compresor (uno para JSON, otro para código, otro para texto) y manda al modelo la versión corta. Los originales se quedan guardados en local y el modelo puede pedirlos si los necesita.
Lo bueno es que se monta en dos comandos y se quita en uno. Lo instalas con pip, ejecutas headroom wrap claude y Claude Code pasa a usar el proxy. headroom unwrap claude lo deja como estaba. El proyecto es open source con licencia Apache-2.0, tiene más de 77K estrellas en GitHub y lista compatibilidad con Codex, Cursor, Goose, OpenClaw y otros agentes.
Lo que no cuenta el titular es cuánto ahorras de verdad. El post habla de hasta un 95%, pero el propio README lo matiza:
«Savings scale with how repetitive the payload is.» (El ahorro depende de lo repetitivo que sea el contenido.) README de Headroom.
En sus cuatro pruebas con salidas reales de herramientas el ahorro va de 21% en búsqueda de código a 57% en depuración de un incidente. La charla normal y la prosa casi no se comprimen. Mide tu caso con headroom savings antes de creerte ninguna cifra.
Antes de instalarlo, dos avisos. wrap añade Serena, un servidor MCP para navegar el código, en la configuración de tu proyecto. Y trae un aviso anónimo de telemetría activado por defecto, que no manda prompts ni código y se apaga con una variable.
Para empezar con agentes de código, programar con un agente de IA. Si ya usas varios a la vez, varios agentes de código sin pisarse. Para gastar cero en tokens con un modelo en tu equipo, IA local con Ollama. Ficha de la herramienta: Claude Code.
Preguntas frecuentes
¿Lo habéis probado?
No. La ficha resume el README de Headroom y el post de @liambraus en X. Las cifras de ahorro son las que publica el proyecto.
¿De verdad ahorra un 95% de tokens?
Solo con contenido muy repetitivo, como listas JSON enormes o logs. En sus cuatro pruebas con agentes el ahorro va de 21% a 57%. Mide el tuyo con headroom savings.
¿Pierdo información al comprimir?
El proyecto guarda los originales en tu equipo y el modelo puede pedirlos con headroom_retrieve si le falta algo. Los bloques pequeños pasan sin tocar.
¿Cuánto cuesta?
Es gratis y open source con licencia Apache-2.0. Hay una versión para equipos con extras, pero para una persona con su portátil no hace falta.
¿Cómo lo quito?
Con headroom unwrap y el nombre del agente, por ejemplo headroom unwrap claude. Eso quita el proxy y el registro de Serena.
Telegram. Suscríbete al canal de Telegram para no perderte nada y estar al loro de todo lo nuevo en automatización y agentes de IA.Unirme al canal