Claves
- —Headroom es una capa intermedia de código abierto que comprime lo que entra al modelo antes de procesarlo.
- —Una búsqueda en código puede pasar de cerca de 18.000 tokens a menos de 1.500, según el repositorio.
- —Su instalación requiere Python 3.10 o superior y el comando pip install «headroom-ai[all]».
Uno de los límites más molestos para quienes usan Claude Code aparece cuando el proyecto crece: archivos, logs y resultados de herramientas consumen la ventana de contexto mucho antes de lo deseado. Headroom busca aliviar ese cuello de botella sin modificar el código.
Headroom comprime lo que entra al modelo antes de procesarlo
Headroom es una capa intermedia de código abierto que se coloca entre el agente y el modelo para comprimir el contenido antes de que llegue al LLM. En Claude Code, la IA no solo recibe instrucciones: también procesa salidas de herramientas, archivos leídos, fragmentos de código relevantes y logs del sistema.
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. El proyecto también incluye benchmarks sobre conjuntos de datos estándar, con resultados prácticamente idénticos a los del modelo sin comprimir; en TruthfulQA, incluso mejora ligeramente.
Detecta JSON, código y texto general para aplicar compresión distinta
Para comprimir, Headroom detecta el tipo de contenido y aplica el algoritmo más adecuado. En estructuras JSON usa un compresor específico, mientras que en código fuente trabaja con el árbol de sintaxis abstracta del lenguaje correspondiente.
En texto general, la herramienta recurre a un modelo propio alojado en Hugging Face llamado Kompress-base, entrenado sobre trazas de agentes reales. Además, incorpora un componente que estabiliza los prefijos del contexto para que la caché del proveedor funcione correctamente y no se regenere en cada petición.
Python 3.10 y tres formas de integrarlo con Claude Code
La instalación es directa para quien ya maneja la línea de comandos: requiere Python 3.10 o superior y ejecutar pip install «headroom-ai[all]». Desde allí, hay tres formas de integrarlo con Claude Code.
La primera es wrap, que lanza Claude Code con Headroom activado de manera transparente mediante headroom wrap claude. La segunda es el modo proxy, que arranca un servidor local para enrutar cualquier cliente compatible con la API de OpenAI. La tercera es MCP, donde headroom mcp install registra las herramientas necesarias y las deja disponibles de inmediato.
La herramienta también incluye headroom learn, una función que analiza sesiones anteriores, detecta fallos o correcciones y escribe notas directamente en el archivo CLAUDE.md del proyecto para evitar que el modelo repita los mismos errores en sesiones futuras.
El repositorio está disponible en GitHub bajo licencia Apache 2.0, con soporte para Python y TypeScript.
