Reducir tokens en Claude Code: Context Mode y Headroom

Para reducir el consumo de tokens en Claude Code, identifica qué ocupa el contexto y evita que la salida innecesaria de las herramientas entre en la conversación. Empieza por los controles nativos; prueba Context Mode para procesar datos de forma selectiva y conservar información al compactar, o Headroom para comprimir mediante un proxy local. Si la mayor parte del consumo procede del razonamiento y de intentos fallidos repetidos, delimita mejor la tarea y revisa la elección del modelo antes de añadir cualquiera de las dos herramientas.

A fecha de 2026-10-21, la versión actual de Claude Code es 2.1.306. La instalación de Headroom que aparece más adelante fija la versión 0.41.0.

¿En qué gasta tokens Claude Code?

Usa /context para averiguar qué ocupa la ventana de contexto y /usage para consultar el consumo y el coste estimado. Responden a preguntas distintas.

Qué necesitas saber	Dónde mirarlo	Qué muestra
¿Por qué se está llenando la conversación?	/context	El espacio ocupado por instrucciones, mensajes, herramientas y otros elementos del contexto
¿Qué ha consumido esta sesión?	/usage	Las categorías de tokens y el coste estimado de la sesión
¿Estoy cerca de agotar el límite de la suscripción?	La información del plan en /usage	El uso del plan, separado de la factura de la API
¿Cuánto se ha cobrado realmente?	Los registros de uso del proveedor que factura	Los cargos según sus tarifas y reglas de facturación

En la versión actual de Claude Code, /cost es un alias de /usage. La cifra en dólares es una estimación: no significa que cada solicitud incluida en Pro o Max genere ese cargo adicional. La documentación de costes de Claude Code explica esta diferencia.

Los registros extensos, las capturas del estado del navegador, los archivos de dependencias y los resultados repetidos de herramientas pueden ocupar una parte considerable del contexto. Los mensajes anteriores también participan en las solicitudes posteriores, pero el almacenamiento de prompts en caché puede abaratar la entrada reutilizada frente a la nueva. Reducir el contenido visible un 50% no implica, por tanto, reducir la factura un 50%.

Usa primero los controles nativos

Elige el control según la causa del gasto: limita la información recuperada cuando la salida contiene demasiado ruido, abre una conversación nueva para trabajos independientes y compacta cuando necesites continuar una tarea larga.

Indica a Claude las rutas exactas, los nombres de los tests que fallan y un comando concreto para verificar el resultado. Pedirle que examine un módulo problemático suele generar menos trabajo innecesario que pedirle que comprenda todo el repositorio antes de hacer un cambio pequeño.

Usa /clear entre tareas no relacionadas, después de guardar las cifras de consumo que necesites. Si vas a continuar con la misma tarea, especifica qué debe conservar /compact:

/compact Preserve the current goal, modified files, failing test names, exact errors, and the next verification command.

El ejemplo pide conservar el objetivo, los archivos modificados, los tests fallidos, los errores exactos y el siguiente comando de verificación. Son prácticas documentadas de gestión del contexto, pero la compactación produce un resumen, no un registro exacto de todo el historial. Guarda también los criterios de aceptación importantes en instrucciones persistentes del proyecto o en notas de la tarea.

Evita compactar después de cada intercambio. La compactación realiza una solicitud para resumir y sustituye el historial, de modo que la siguiente solicitud debe establecer un prefijo más corto en la caché. Compactar con demasiada frecuencia puede ahorrar contexto a cambio de más trabajo y de reconstruir la caché.

Para tareas sencillas, prueba /effort low si el modelo admite ese control de esfuerzo de razonamiento. Reducir el esfuerzo puede disminuir el trabajo de razonamiento, pero no encoge un registro que una herramienta ya ha devuelto. Los cambios introducidos mediante el comando se guardan para el modelo seleccionado: restaura tu ajuste habitual después de comparar. La documentación de configuración de modelos explica los controles admitidos y los alias.

Los subagentes ofrecen otra forma nativa de aislar contexto: trabajan por separado y devuelven un resumen. Así protegen la conversación principal, aunque sus solicitudes también consumen tokens.

Context Mode o Headroom: ¿cuál probar?

Elige Context Mode si puedes reducir los datos antes de devolvérselos a Claude. Elige Headroom si quieres que las llamadas existentes a herramientas pasen por una capa de compresión.

Qué limita tu trabajo	Qué probar primero	Qué cambia
Archivos o registros grandes que pueden consultarse o procesarse localmente	Context Mode	Claude recibe resultados seleccionados mediante herramientas de ejecución y búsqueda
Se pierde parte del estado de la tarea al compactar	Context Mode	Los manejadores de eventos, o hooks, registran sucesos y restauran información para continuar
Las herramientas habituales devuelven una salida demasiado extensa	Headroom	Un proxy local comprime el contenido apto antes de reenviar las solicitudes
Tareas cortas cuyo consumo se concentra en razonamiento o reintentos	Los controles nativos de alcance, esfuerzo y modelo	Se reduce el trabajo requerido antes de introducir otro componente

Prueba una herramienta cada vez para poder atribuirle el resultado.

Los porcentajes publicados no son directamente comparables. El material de evaluación de Context Mode mide bytes de salida en ejemplos seleccionados. Las cifras de 21%–57% de Headroom proceden de pruebas sin conexión con salidas sintéticas reproducibles de herramientas. Ninguna determina cuánto bajará la factura de una sesión completa de Claude Code, ni sustituye la comprobación de que la tarea sigue resolviéndose correctamente.

Context Mode: devuelve el resultado, no el archivo entero

Context Mode resulta útil cuando una operación local puede obtener la respuesta sin introducir todos los datos de entrada en la conversación. Su plugin también registra determinados eventos de la sesión en SQLite y utiliza hooks para restaurar información que permita continuar después de compactar.

El paquete actual requiere Node.js 22.5.0 o posterior. Comprueba tu instalación en Bash:

claude --version
node --version

Dentro de Claude Code, sigue la instalación desde el marketplace documentada por el proyecto:

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Reinicia Claude Code y ejecuta:

/context-mode:ctx-doctor

El comando de diagnóstico comprueba, entre otros componentes, los entornos de ejecución, el registro del plugin, los hooks y la capacidad de búsqueda de SQLite. Resuelve los fallos pertinentes antes de dar por activo el plugin. Instalar solo su servidor MCP no proporciona la misma integración con los eventos de la sesión.

Para comprobarlo con un caso concreto, abre un proyecto npm que ya tenga un package-lock.json de versión 2 o 3. Pide a Claude que invoque ctx_execute_file con path: "package-lock.json", language: "javascript" y este código:

const lock = JSON.parse(FILE_CONTENT);
if (!lock.packages) {
  console.log("This example requires an npm v2/v3 lockfile.");
} else {
  const rows = Object.entries(lock.packages).filter(([path]) => path !== "");
  console.log(JSON.stringify({
    lockfileVersion: lock.lockfileVersion,
    packageEntries: rows.length,
    entriesMarkedDev: rows.filter(([, pkg]) => pkg.dev === true).length
  }, null, 2));
}

La herramienta proporciona el contenido del archivo mediante FILE_CONTENT. El resultado esperado es un pequeño objeto JSON con los tres campos solicitados, en lugar del archivo completo. Los valores dependen del proyecto: cuentan entradas del archivo de dependencias, no nombres de paquetes únicos.

A continuación, ejecuta:

/context-mode:ctx-stats

El comando de estadísticas debería mostrar actividad de Context Mode. Si no registra llamadas, todavía no has demostrado que se haya utilizado la vía solicitada. Sus cifras de reducción de salida no son un cálculo de facturación.

Aplica el mismo patrón a los registros: calcula los totales localmente, selecciona los errores pertinentes y devuelve fragmentos exactos con su ubicación de origen. Mantén las lecturas directas para archivos fuente pequeños cuyo código Claude necesite ver con precisión.

Context Mode utiliza Elastic License 2.0. Su aislamiento de ejecución tampoco equivale a una zona de ejecución completamente protegida por el sistema operativo: las herramientas pueden heredar acceso al sistema de archivos. Conserva los permisos y controles de aislamiento que utilizas normalmente para los comandos ejecutados por agentes.

Headroom: comprime la salida mediante un proxy local

Headroom encaja cuando quieres conservar las herramientas habituales de Claude Code mientras un proxy reduce la salida apta para compresión. Su comportamiento predeterminado para programación también tiene en cuenta la estabilidad de la caché; no promete comprimir todos los archivos fuente ni todas las solicitudes.

Este ejemplo utiliza una clave de API de Anthropic Console, por lo que genera cargos de API independientes de la suscripción a Claude. Presupone que tienes instalados uv y Claude Code, que no hay un proxy Headroom ya en marcha y que no existe una configuración activa incompatible de gateway personalizado o proveedor de nube. Los gateways corporativos existentes necesitan su propia integración.

En Bash, instala la versión fijada del paquete con soporte de proxy, siguiendo la guía de instalación de Headroom:

uv tool install --python 3.13 "headroom-ai[proxy]==0.41.0"
headroom --version

La comprobación debería indicar 0.41.0. Ejecuta la lectura de la clave, introdúcela sin que se muestre en pantalla y pulsa Enter; después, inicia Claude mediante Headroom:

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
HEADROOM_TELEMETRY=on HEADROOM_BEACON=off headroom wrap claude --code-memory none

Autoriza el uso de la clave personalizada si Claude lo solicita y consulta /status para confirmar la credencial y el modelo activos. Si antes rechazaste esa clave, la documentación de autenticación describe el ajuste «Use custom API key» de /config.

El lanzador inicia o reutiliza un proxy local, ejecuta Claude a través de él y registra el servidor MCP de Headroom para recuperar datos originales en la configuración de Claude Code. --code-memory none omite la integración adicional de Serena, pero mantiene disponible la recuperación de Headroom. No añadas --no-mcp a este ejemplo: eliminaría la vía de recuperación asociada a los marcadores de contenido comprimido. Las opciones se definen en la implementación del lanzador de la versión 0.41.0.

Las variables de entorno activan la recopilación local de telemetría y desactivan su envío opcional. Las solicitudes siguen llegando al proveedor de modelos configurado.

Anota la dirección del proxy que aparece al arrancar. El puerto habitual es 8787, pero el lanzador puede elegir otro disponible. En un segundo terminal Bash, sustituye el puerto si es necesario:

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8787/stats

Ahora encarga a Claude, ejecutado mediante Headroom, una tarea acotada sobre un test.log existente y de tamaño considerable: enumerar los tests fallidos sin duplicados y citar el primer error exacto de cada uno, sin modificar archivos. Al terminar, vuelve a consultar /stats.

Una respuesta de estado saludable demuestra que el proxy está funcionando. El aumento de requests.total muestra que se han contabilizado solicitudes completadas; revisa por separado requests.failed y requests.rate_limited. La documentación de métricas explica estos campos. Que no haya ahorro con una entrada breve o protegida frente a la compresión no demuestra un fallo de enrutamiento.

Si falla la autenticación, comprueba posibles conflictos de ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL y de la configuración del proveedor antes de reintentar. Si no aparecen solicitudes, verifica el puerto anunciado y la ruta utilizada por la sesión que acabas de iniciar.

El mecanismo de compresión, caché y recuperación de Headroom permite recuperar originales retenidos cuando Claude necesita detalles omitidos. La recuperación añade trabajo y la retención tiene un límite; si el original ya no está disponible, vuelve al archivo fuente o ejecuta de nuevo el comando.

Después de salir de Claude, revierte la configuración de esta prueba en el terminal original, desde el mismo proyecto y con el puerto correcto:

headroom unwrap claude --port 8787
unset ANTHROPIC_API_KEY

El comando unwrap elimina la configuración gestionada por Headroom e intenta detener el proxy correspondiente. unset retira del entorno la clave de API exportada para esta prueba. Comprueba /status antes de volver a tu forma habitual de autenticación.

Reserva los modelos más baratos para subtareas acotadas

Utiliza un modelo de menor precio en tareas cuyo resultado puedas verificar con poco esfuerzo, como extraer fallos de un registro concreto. Esto cambia el precio del trabajo; no garantiza que se consuman menos tokens.

Para establecer una referencia con las funciones nativas, crea .claude/agents/log-summary.md:

---
name: log-summary
description: Summarize supplied test logs and identify failing tests.
model: haiku
tools: Read, Grep, Glob
maxTurns: 6
---

Read only the log paths supplied in the task.
Return failing test names, exact error excerpts, and file or line references.
Report uncertainty and missing evidence.
Do not modify files.

La configuración restringe las herramientas a lectura y búsqueda, y pide errores exactos con referencias al archivo de origen. Reinicia Claude Code después de crear el directorio de agentes e invoca el subagente sobre un registro existente:

Use log-summary to inspect ./test.log and return the first failing test and its exact error. Stop after the summary.

Consulta /tasks mientras trabaja para comprobar su modelo real y contrasta el fragmento devuelto con el registro original. maxTurns limita los turnos, no los dólares ni los tokens; al alcanzar el límite, el resultado puede quedar incompleto. Los campos y los detalles de carga están documentados en la referencia de subagentes.

haiku es un alias: la configuración del proveedor determina el modelo concreto. Deja las decisiones de diseño difíciles y la depuración ambigua al modelo que las resuelva con fiabilidad. Un subagente barato que requiere correcciones repetidas puede encarecer el conjunto.

Si utilizas BetterToken para acceder a modelos con pago por uso, sigue su configuración de Claude Code: la URL base compatible con Anthropic es https://bettertoken.ai, sin /v1. Revisa ANTHROPIC_DEFAULT_HAIKU_MODEL y las demás asignaciones de alias. Si todos apuntan al mismo ID de modelo, elegir haiku no seleccionará otro modelo más barato. Escoge deliberadamente IDs admitidos, compara las tarifas actuales de modelos y caché y comprueba el modelo registrado y el cargo. La facturación de la API de BetterToken es independiente de una suscripción a Claude; trata esta configuración de proveedor por separado de la prueba de Headroom con conexión directa a Anthropic.

Decide según el coste total y la corrección de la tarea

Conserva una herramienta de compresión solo si mejora el resultado de la tarea completa después de incluir los efectos de la caché, los subagentes, la recuperación y los reintentos.

Compara el mismo estado del repositorio, prompt, modelo concreto, nivel de esfuerzo y comando de verificación. Registra si cada ejecución empieza con una caché ya preparada o una caché fría, porque mezclar ambas condiciones puede distorsionar la comparación. Comprueba tanto el cambio o la respuesta final como las pruebas exactas que aporta.

En la contabilidad de la API de Anthropic, input_tokens, cache_creation_input_tokens y cache_read_input_tokens son categorías separadas: input_tokens no representa por sí solo toda la entrada. Incluye también los tokens de salida. Si las tarifas se expresan por millón de tokens, calcula sum(token_count × category_rate / 1,000,000) para todas las solicitudes, separando las escrituras en caché según su duración cuando tengan precios distintos. Añade los cargos obligatorios que no dependan de los tokens.

La visualización de caché de la conversación principal requiere Claude Code 2.1.251 o posterior y no incluye subagentes. Los contadores de ahorro del proxy sirven para diagnosticar, pero compara el gasto con los registros del proveedor que factura.

Si un error omitido obliga a investigar de nuevo, un subagente necesita ayuda repetidamente o la recuperación reconstruye el volumen original de contexto, reduce la compresión o cambia los límites de la tarea. El resultado útil es una solución correcta con menos trabajo total facturado.