Uso Claude Code y este hack me ayuda a reducir un 90% del consumo de tokens

Uno de los problemas que enfrentan los usuarios de Claude es llegar al tope de los límites de tokens mucho antes de lo que les gustaría. Esto es más evidente con Claude Code cuando manejas proyectos con muchos archivos, logs o resultados de herramientas. La buena noticia es que existe un hack para sacarle más partido a la herramienta de programación de Anthropic sin tocar el código.

Headroom es una capa intermedia de código abierto que comprime todo lo que entra al modelo antes de que lo procese, con la promesa de mantener la misma calidad de respuestas. Antes de explicar cómo funciona, tenemos que analizar la forma como opera Claude Code.

Cuando usas Claude Code en un proyecto, la IA no solo procesa tus instrucciones. También recibe los resultados de cada herramienta que ejecuta, los contenidos de los archivos que lee, los fragmentos de código relevantes o los logs del sistema, ocupando espacio en la ventana de contexto.

Headroom se coloca entre tu agente y el modelo, analiza ese contenido y lo comprime de forma inteligente antes de que llegue al LLM. Según los datos del repositorio, una búsqueda en código que normalmente consume cerca de 18.000 tokens puede quedar por debajo de 1.500 tras pasar por la herramienta, lo que representa una reducción del 92%. En sesiones de depuración de incidentes, los resultados son similares, y en la exploración de repositorios completos, la ventana se recorta casi a la mitad.

Headroom reduce hasta en 92% el consumo de tokens

Lo mejor de todo es que la compresión no sacrifica la precisión de las respuestas. El proyecto incluye benchmarks sobre conjuntos de datos estándar y los resultados son prácticamente idénticos a los del modelo sin comprimir. En algunos casos, como en el benchmark de veracidad TruthfulQA, la puntuación incluso mejora ligeramente.

Para llevar a cabo la compresión, Headroom detecta el tipo de contenido que está procesando y aplica el algoritmo más adecuado. Para estructuras JSON usa un compresor específico, mientras que para código fuente trabaja con el árbol de sintaxis abstracta del lenguaje en cuestión.

En los casos de texto general, la herramienta recurre a un modelo propio alojado en Hugging Face llamado Kompress-base, el cual se entrenó sobre trazas de agentes reales. Headroom también echa mano de un componente adicional que estabiliza los prefijos del contexto para que la caché del proveedor funcione correctamente y no se regenere en cada petición.

Ahorro en cargas de trabajo de agentes reales:

Cómo usar Headroom en Claude Code

La instalación de Headroom es rápida para aquellos que ya están familiarizados con la línea de comandos. El requisito principal es instalar Python 3.10 o superior y ejecutar pip install "headroom-ai[all]" para tener todo disponible. A partir de ahí, tienes tres formas de integrarlo con Claude Code.

El modo más directo es el wrap, que lanza Claude Code con Headroom activado de manera transparente mediante headroom wrap claude, sin modificar nada en tu configuración existente. Si prefieres una solución centralizada que cubra varios agentes a la vez, el modo proxy arranca un servidor local al que puedes enrutar cualquier cliente compatible con la API de OpenAI. Y para quien ya trabaja con el protocolo MCP, headroom mcp install registra las herramientas necesarias y las deja disponibles de inmediato.

Hay una funcionalidad adicional que va más allá de la compresión pura. Conocida como headroom learn, esta opción analiza las sesiones anteriores, detecta los fallos o correcciones que se han producido y escribe notas directamente en el archivo CLAUDE.md del proyecto para que el modelo no repita los mismos errores en sesiones futuras.

Si quieres probarlo, el repositorio está disponible en GitHub bajo licencia Apache 2.0, con soporte para Python y TypeScript.