Repolode
Enviar
headroomlabs-ai

headroomlabs-ai/headroom

Comprime resultados de herramientas, logs, archivos y fragmentos RAG antes de enviarlos a un LLM, como biblioteca, proxy o servidor MCP.

Ver en GitHubSitio web
Estrellas
76,105
Forks
5,915
Issues abiertos
482
Último commit
hace 3 días

¿Qué es?

Headroom es una capa de compresión de contexto para agentes de IA y aplicaciones con LLM. Comprime resultados de herramientas, logs, fragmentos RAG, archivos e historial de conversaciones antes de enviarlos al modelo. La compresión se ejecuta localmente en el equipo del usuario. Un enrutador de contenido detecta el tipo de cada carga: el JSON se procesa con SmartCrusher, el código fuente con CodeCompressor, que tiene en cuenta el AST, y la prosa con el modelo Kompress-v2-base.

Se puede usar como biblioteca integrada en Python o TypeScript mediante compress(messages), como proxy intercambiable que no requiere cambios en el código, con headroom wrap para agentes de programación como Claude Code, Codex, Cursor y Aider, o como servidor MCP. La compresión es reversible: los originales se almacenan en caché localmente y el modelo puede recuperarlos cuando los necesita.

El ahorro depende de la carga. Las pruebas de rendimiento del proyecto muestran una reducción de entre el 21 % y el 57 % de los tokens en cargas de trabajo de agentes de ejemplo, y la compresión es mucho mayor en JSON y logs repetitivos. La prosa y el texto que ya es denso apenas se reducen.

Funciones clave

  • 01Enrutamiento por tipo de contenido que selecciona un compresor para JSON, código o prosa.
  • 02Compresión reversible: los originales se almacenan en caché localmente y se pueden recuperar cuando se necesitan.
  • 03Proxy que no requiere cambios en el código y wrappers de un solo comando para agentes de programación populares.
  • 04Bibliotecas de Python y TypeScript que ofrecen compress() para uso integrado.
  • 05Servidor MCP con herramientas para comprimir, recuperar y consultar estadísticas.
  • 06Procesamiento local, por lo que el contenido de los prompts y los archivos no se envía a un servicio para comprimirlo.

Casos de uso

  • Reducir los costos de tokens de agentes de programación como Claude Code o Cursor durante sesiones largas con mucho contenido generado por herramientas.
  • Comprimir volcados de logs o resultados de búsqueda en JSON de gran tamaño antes de enviarlos a un modelo para depurar.
  • Reducir el tamaño de los fragmentos RAG recuperados en una canalización existente de LangChain o LiteLLM.
  • Enrutar varios agentes a través de un proxy y una capa de memoria compartidos.

Inicio rápido

  1. 1

    Instala la CLI con uv

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

    O instala el paquete de Python con pip

    pip install "headroom-ai[all]"
  3. 3

    Inicia el proxy drop-in en el puerto 8787

    headroom proxy --port 8787
  4. 4

    Comprueba la instalación con la comprobación de estado

    headroom doctor

Antes de usarlo

  • El ahorro varía mucho; la prosa y las salidas que ya son densas apenas se comprimen.
  • Las pruebas de compresión del README son resultados declarados por el propio proyecto y se ejecutan en escenarios específicos con datos iniciales.

Temas

#llm#context-window#token-optimization#rag#mcp#coding-agents#proxy#prompt-engineering#agent#ai

Preguntas frecuentes

¿Qué es headroom?
Comprime resultados de herramientas, logs, archivos y fragmentos RAG antes de enviarlos a un LLM, como biblioteca, proxy o servidor MCP. Headroom es una capa de compresión de contexto para agentes de IA y aplicaciones con LLM. Comprime resultados de herramientas, logs, fragmentos RAG, archivos e historial de conversaciones antes de enviarlos al modelo. La compresión se ejecuta localmente en el equipo del usuario. Un enrutador de contenido detecta el tipo de cada carga: el JSON se procesa con SmartCrusher, el código fuente con CodeCompressor, que tiene en cuenta el AST, y la prosa con el modelo Kompress-v2-base.
¿headroom es gratuito? ¿Qué licencia tiene?
headroom es open source bajo la licencia Apache-2.0. Revisa los términos de la licencia antes de usarlo en productos comerciales.
¿headroom sigue mantenido?
Mantenimiento activo. El último commit de headroom fue el 17 oct 2026.
¿Para qué puedo usar headroom?
Reducir los costos de tokens de agentes de programación como Claude Code o Cursor durante sesiones largas con mucho contenido generado por herramientas. Comprimir volcados de logs o resultados de búsqueda en JSON de gran tamaño antes de enviarlos a un modelo para depurar. Reducir el tamaño de los fragmentos RAG recuperados en una canalización existente de LangChain o LiteLLM. Enrutar varios agentes a través de un proxy y una capa de memoria compartidos.
¿Cómo se instala headroom?
Instala la CLI con uv: uv tool install --python 3.13 "headroom-ai[all]" O instala el paquete de Python con pip: pip install "headroom-ai[all]" Inicia el proxy drop-in en el puerto 8787: headroom proxy --port 8787 Comprueba la instalación con la comprobación de estado: headroom doctor
¿Dónde consigo headroom?
El código fuente y las instrucciones de instalación están en GitHub: https://github.com/headroomlabs-ai/headroom

Resumen generado por IA a partir del README del proyecto. Las estadísticas de GitHub se actualizan a diario.

Proyectos relacionados