Herramientas de desarrollo

Tutorial de Headroom: ahorrar contexto para Claude Code, Codex y AI Agents

Headroom es una herramienta de compresión de contexto para AI Agents. Esta guía cubre instalación, uso con Claude/Codex/Cursor wrap, MCP Server, modo proxy y reducción de tokens en logs, salidas de herramientas y fragmentos RAG.

chopratejas/headroom es una herramienta de compresión de contexto para agentes de IA. El problema que resuelve es muy realista: mientras el agente ejecuta comandos, lee registros, busca código y rellena fragmentos de RAG, la ventana de contexto pronto se llenará y el costo y la demora aumentarán juntos.

La idea detrás de Headroom es comprimir la salida de la herramienta, registros, archivos, clips RAG e historial de sesiones antes de que el contenido ingrese a LLM. El objetivo escrito en el README es muy sencillo: reducir los tokens 60-95% mientras se intenta mantener la calidad de las respuestas.

¿Qué problema resuelve?

Muchas herramientas de agentes ahora no tienen modelos que no sean lo suficientemente inteligentes, pero el contexto es demasiado sucio:

  • grep, rg, la consulta de registro devuelve cientos o miles de filas a la vez;
  • Los fragmentos de búsqueda RAG son repetidos, redundantes y formateados;
  • Hay una gran cantidad de campos de bajo valor en JSON, seguimiento de pila y resultados de SQL;
  • Después de varias rondas de depuración, la salida anterior ocupa el contexto;
  • Herramientas como Claude Code, Codex, Cursor y Aider mantienen el contexto, lo que dificulta compartir la memoria.

El espacio libre es el “limpiador antes de entrar al modelo”. No reemplaza a LLM ni reemplaza a RAG, pero agrega una capa de compresión, enrutamiento, almacenamiento en caché y recuperación rastreable frente a LLM.

Competencias básicas

Desde README, Headroom tiene varias formas de uso principales:

  • Biblioteca: llame directamente a compress(messages) en Python o TypeScript;
  • Proxy: utilice headroom proxy --port 8787 como proxy compatible con OpenAI;
  • Ajuste del agente: use headroom wrap claude|codex|cursor|aider|copilot para ajustar un Agente existente;
  • Servidor MCP: proporciona headroom_compress, headroom_retrieve, headroom_stats para uso de clientes MCP;
  • Memoria entre agentes: permita que Claude, Codex, Gemini y otras herramientas compartan la memoria local y eliminen automáticamente los duplicados;
  • headroom learn: busca experiencia en sesiones fallidas, escribe CLAUDE.md o AGENTS.md;
  • Compresión reversible: el texto original no se eliminará y podrá recuperarse a través de la herramienta de búsqueda si es necesario.

Estas formas son cruciales. No es un SDK que solo pueda incrustarse en el código, ni puede usarse solo como proxy. Puede comenzar con el modo de ajuste más ligero y decidir si lo integra en su propia aplicación.

¿Cómo se comprime?

Hay varias palabras clave en la estructura de Headroom:

  • ContentRouter: identifica el tipo de contenido y selecciona el compresor correspondiente;
  • SmartCrusher: prefiere procesar contenido estructurado como JSON;
  • CodeCompressor: prefiere procesar código y AST;
  • Kompress-base: utilizado para la compresión de texto;
  • CacheAligner: hace que el prefijo del mensaje sea más estable y mejora la tasa de aciertos de la caché KV del proveedor;
  • CCR: guarde el texto original y recupérelo mediante recuperación cuando sea necesario.

En términos humanos, no resume aproximadamente todo el contenido en un párrafo, sino que primero determina el tipo de contenido y luego selecciona diferentes estrategias de compresión. El código, JSON, texto sin formato, registros y fragmentos RAG no se deben comprimir de la misma manera.

Instalación rápida

El método de instalación que figura en el archivo README es muy sencillo:

1
2

pip install "headroom-ai[all]"
npm install headroom-ai

El lado de Python requiere Python 3.10+. Después de la instalación, puedes probar estos comandos primero:

1
2
3

headroom wrap claude
headroom proxy --port 8787
headroom perf

Si está utilizando el cliente MCP, puede ir:

1

headroom mcp install

Si solo desea verificar el efecto, lo más fácil es ejecutar headroom perf primero para ver cuántos tokens puede guardar para cargas de trabajo típicas. Después de confirmar que está disponible, conéctelo a Claude Code, Codex, Cursor o su propio cliente compatible con OpenAI.

¿Cuál es la diferencia entre ## y resumen ordinario?

El mayor problema de los resúmenes ordinarios es que son irreversibles. El registro se resume como “Error en la conexión de la base de datos” y no puede ver el código de error original, la marca de tiempo, la pila de llamadas ni el contexto. Si el Agente necesita detalles más adelante, solo podrá verificarlos nuevamente.

Uno de los puntos clave de Headroom es reversible: el contenido original se guarda localmente, se comprime y se pasa al modelo; si el modelo requiere el texto original, se recupera a través de headroom_retrieve. Este diseño es más adecuado para la depuración, la búsqueda de código y el análisis de registros de producción, porque estos escenarios a menudo requieren volver a los detalles.

Por supuesto, esto también significa que debe administrar los límites de privacidad y almacenamiento local. Aunque README enfatiza lo local primero, siempre que envíe el contenido comprimido al modelo de nube, aún deberá manejarlo de acuerdo con sus propios requisitos de seguridad de datos.

¿Qué escenarios son adecuados?

Creo que Headroom es el más adecuado para estos escenarios:

  • Claude Code, Codex y Cursor a menudo se ralentizan porque la salida de la herramienta es demasiado larga;
  • Utilice el Agente para analizar grandes almacenes, resultados de búsqueda y fragmentos de archivos que pueden explotar fácilmente el contexto;
  • Al solucionar problemas, SRE debe mostrar registros, seguimientos, configuraciones y salida de comandos al modelo;
  • Al realizar aplicaciones RAG, los resultados de la búsqueda son muy redundantes;
  • Quiere compartir la memoria local entre múltiples herramientas del Agente;
  • Quiere integrar herramientas MCP en flujos de trabajo de IA existentes.

Si solo solicita algunos chats de vez en cuando, o el mensaje es muy breve, no necesariamente lo necesita. El valor de Headroom aparece principalmente cuando “El agente realmente está trabajando”.

¿A qué debes prestar atención al usarlo?

La compresión contextual no es mágica. Puede ahorrar tokens, pero también puede traer nuevos problemas:

  • Cuando la estrategia de compresión es inapropiada, es posible que el modelo no pueda obtener detalles clave;
  • Los escenarios de código y registro deben probar si la recuperación es confiable;
  • Al aceptar el modo proxy, confirme por qué enlaces locales y de nube pasa la solicitud;
  • Cuando lo utilicen equipos, se deben definir políticas de almacenamiento en caché local, grabación de sesiones y retención de datos confidenciales;
  • No se limite a observar los ahorros simbólicos, sino también la tasa de finalización de tareas y la tasa de errores de cálculo.

Mi sugerencia es realizar pruebas con tareas reales en lugar de simplemente ver demostraciones. Por ejemplo, tome un conjunto de errores históricos, registros de CI, consultas RAG y tareas de búsqueda de código, y compare el costo, la velocidad y la calidad de la respuesta de “alimentar el modelo directamente” y “pasar por Headroom”, respectivamente.

Resumen

Headroom es una herramienta típica de “ingeniería contextual”. No busca recrear un Agente, sino que se interpone entre el Agente y el LLM, limpiando y acortando el contenido que ingresa al modelo, conservando al mismo tiempo la capacidad de recuperar el texto original.

Es adecuado para personas que ya utilizan las herramientas Claude Code, Codex, Cursor, Aider, Copilot CLI o MCP. Si su punto débil es “el contexto del modelo a menudo se ve abrumado por los registros y la salida de la herramienta”, vale la pena probar Headroom; Si su problema es simplemente capacidades insuficientes del modelo, es posible que simplemente comprimir el contexto no necesariamente lo resuelva.

Optimización nativa de tokens y caché en Claude Code

Prompt Cache no guarda texto plano

Prompt Cache no es solo una caché de cadenas de texto. En la inferencia Transformer, lo importante es el estado Key/Value calculado por las capas de atención a partir del prefijo de contexto, lo que solemos llamar KV cache.

Eso implica dos cosas:

  • Si el prefijo se mantiene estable, parte del cálculo previo puede reutilizarse.
  • Si cambian el modelo, las definiciones de herramientas, el prompt del sistema o los mensajes iniciales, las entradas antiguas de caché pueden dejar de coincidir.

La documentación de Anthropic resume la jerarquía de invalidación como tools -> system -> messages. Cambiar definiciones de herramientas puede invalidar toda la caché; cambios en system afectan system y messages; cambios en messages afectan sobre todo la caché de mensajes.

Claude Code añade otras fuentes de contexto como CLAUDE.md, Skills, MCP, plugins y subagents, así que es fácil romper la caché sin querer.

Asesino de caché 1: cambiar de modelo a mitad de tarea

Cambiar de modelo es una de las operaciones más caras.

Prompt Cache está aislada por modelo. Opus, Sonnet y Haiku tienen arquitecturas y pesos distintos, así que el KV cache calculado desde el mismo texto no es intercambiable. Si construyes un contexto largo en Opus y luego cambias a Sonnet, Sonnet no puede reutilizar la caché de Opus.

Esto produce un resultado poco intuitivo: cambiar a un modelo más barato a mitad de tarea puede hacer inútil la caché acumulada. El contexto que podría leerse a precio de cache read quizá tenga que escribirse y calcularse de nuevo.

Un patrón más estable:

  • Mantén la conversación principal en un solo modelo.
  • Usa un subagent para tareas laterales que puedan ejecutarse con un modelo más barato.
  • Deja que el agente lateral busque, explore o resuma, y devuelva un resultado breve a la conversación principal.

Así el prefijo largo de la conversación principal se mantiene estable y la caché acierta con más consistencia.

Asesino de caché 2: añadir MCP o recargar plugins a mitad de tarea

MCP proporciona herramientas a Claude Code. Al añadir un servidor MCP, cambia la lista de herramientas, y las definiciones de herramientas están en el extremo izquierdo de la cadena de contexto.

Desde la perspectiva de Prompt Cache, cuando cambia la lista de herramientas, system y messages pueden necesitar recalcularse. Si usas muchos MCP, las definiciones de herramientas pueden ocupar muchos tokens, y el costo de invalidación se nota.

Un detalle importante: Claude Code suele leer la configuración MCP al iniciar la sesión. Cambiar configuración durante la sesión no siempre afecta de inmediato. Los momentos peligrosos son reiniciar, hacer resume, recargar plugins o reconstruir la lista de herramientas.

Recomendaciones:

  • Instala los MCP necesarios antes de iniciar una tarea larga.
  • Evita descubrir a mitad de trabajo que falta una herramienta y recargar.
  • Reduce los MCP habilitados por defecto cuando sea posible.
  • No mantengas servidores MCP raramente usados siempre activos.

Las definiciones de herramientas estables son la base de una Prompt Cache estable.

Asesino de caché 3: editar CLAUDE.md durante la sesión

CLAUDE.md es el archivo de memoria de proyecto de Claude Code. Sirve para comandos de build, tests, convenciones de arquitectura, estilo de código y restricciones del proyecto.

Es útil, pero también entra en el contexto. La ayuda de Claude explica que CLAUDE.md se lee al iniciar la sesión y se entrega como mensaje de usuario. También se beneficia de Prompt Cache: la primera petición paga el precio completo de entrada, y las siguientes pueden usar el precio menor de cache read si la caché sigue válida.

El problema es que CLAUDE.md se identifica por contenido. Si cambias el archivo, la caché antigua deja de coincidir.

Por eso conviene no editar CLAUDE.md con frecuencia durante tareas largas. Mejor:

  • Revisa si CLAUDE.md es suficiente antes de empezar.
  • Coloca reglas estables en el archivo e instrucciones temporales en la conversación.
  • No edites la memoria de largo plazo por una necesidad puntual.
  • Si debes cambiarlo, trata la siguiente fase como una nueva sesión o etapa.

CLAUDE.md debería ser guía estable de proyecto, no un borrador temporal que cambia cada ronda.

Asesino de caché 4: instalar o actualizar Skills a mitad de tarea

Skills también forman parte del contexto. Instalar una Skill nueva, actualizar una Skill o cambiar la lista de Skills cambia lo que se inyecta en la sesión.

Estos cambios suelen aplicarse al recargar, reanudar o abrir una nueva sesión. Cuando messages se reconstruye, las entradas antiguas de caché pueden dejar de servir.

La recomendación es similar a MCP:

  • Decide qué Skills necesitas antes de empezar.
  • Mantén estable el conjunto de Skills para tareas similares.
  • Evita instalar Skills en mitad de una tarea larga.
  • Si instalas una Skill nueva, trátalo como inicio de una nueva etapa.

Para flujos repetibles como producción de contenido, review, despliegue o traducción, mantener un conjunto fijo de Skills ayuda a estabilizar la estructura del contexto.

Asesino de caché 5: estar inactivo más allá del TTL

Prompt Cache no dura para siempre. Un TTL común está en el orden de minutos, y la documentación relacionada con Claude Code suele hablar de una ventana cercana a cinco minutos. Pasado el TTL, incluso la misma petición puede requerir reconstruir la caché.

Esto explica una sensación común en tareas largas: todo iba rápido y barato, sales por un café, vuelves y el costo de tokens sube otra vez.

Es fácil que ocurra. Lees la salida de Claude Code, inspeccionas archivos, ejecutas tests o piensas el siguiente paso. Cinco minutos pasan rápido.

Si tu entorno lo permite, puedes pedir un TTL de una hora antes de tareas largas:

1

export ENABLE_PROMPT_CACHING_1H=1

En Windows PowerShell:

1

$env:ENABLE_PROMPT_CACHING_1H="1"

Las escrituras de caché de una hora suelen costar más que las de cinco minutos. No siempre conviene para tareas cortas, pero en bases de código grandes, conversaciones largas y trabajos complejos de varias etapas, puede ser más barato que sufrir expiraciones repetidas.

Un flujo de Claude Code que ahorra tokens

Un flujo más estable sería:

  1. Elegir el modelo antes de empezar y evitar cambios frecuentes.
  2. Habilitar los MCP necesarios y desactivar los que no usarás.
  3. Mantener CLAUDE.md breve, estable y centrado en reglas duraderas.
  4. Preparar por adelantado las Skills necesarias.
  5. En tareas complejas, considerar TTL de una hora.
  6. Dividir la tarea en fases, pero mantener estable la estructura de contexto dentro de cada fase.
  7. Usar subagents o sesiones separadas para exploraciones laterales, sin alterar la conversación principal.

El objetivo no es eliminar todos los fallos de caché. Es evitar los fallos caros y fáciles de pasar por alto.

Regla rápida

Hazte esta pregunta:

¿Esta operación cambia el modelo, las definiciones de herramientas, el contexto del sistema o los mensajes fijos del inicio de la sesión?

Si la respuesta es sí, probablemente afecte a Prompt Cache. Cuanto más a la izquierda esté en la cadena de contexto, mayor será el impacto.

Operaciones comunes:

  • Cambiar modelo: alto riesgo, cachés aisladas por modelo.
  • Añadir MCP o recargar plugins: alto riesgo, cambia la lista de herramientas.
  • Editar CLAUDE.md: riesgo medio-alto, cambia la memoria del proyecto.
  • Instalar Skills: riesgo medio-alto, cambia el contexto inyectado.
  • Continuar una conversación normal: bajo riesgo, principalmente añade messages.
  • Superar el TTL en inactividad: alto riesgo, la caché del servidor expira.

Resumen

Optimizar Prompt Cache en Claude Code consiste en mantener estable el prefijo de la sesión.

No cambies modelos sin necesidad. No instales MCP y Skills a mitad de trabajo. No uses CLAUDE.md como borrador temporal. En tareas complejas, considera un TTL más largo. Con estas bases estables, el costo en tokens y la velocidad de respuesta se vuelven mucho más predecibles.

La frase práctica es: configura antes de empezar, cambia menos después.

Fuentes de referencia

Preguntas frecuentes

¿Qué es este proyecto?

Es un proyecto de herramientas de IA cubierto en este artículo, con foco en qué hace, cómo se usa y cuándo merece la pena probarlo.

¿Para quién es?

Principalmente para desarrolladores y usuarios de herramientas de IA que quieren conectarlo a flujos reales, no solo leer el README.

¿Qué conviene revisar antes de usarlo?

Revisa instalación, herramientas compatibles, límites de datos y permisos, y si el proyecto sigue cambiando rápido.

¿Sirve para producción?

Conviene probarlo primero en un flujo pequeño. Verifica el comportamiento antes de usarlo en tareas sensibles o de producción.