Uso de tokens en Claude Code: mantén la salida de herramientas fuera del contexto

Tu agente ejecutó la suite de pruebas tres veces, y la factura es más grande que la tarea. La razón rara vez es el código que escribió. Son los registros de pruebas: una vez que el resultado de una herramienta llega al contexto de Claude Code, cada solicitud posterior lo vuelve a llevar. La solución es reducir la salida de las herramientas antes de que el modelo la vea. La forma oficial es un hook PreToolUse en Bash; la forma de terceros es el plugin context-mode. Ambas están a continuación, con una estimación de costos para una sesión larga en un modelo de CheapTokens.

Por qué un registro se paga muchas veces#

Según la página de costos de Claude Code (https://code.claude.com/docs/en/costs, consultada el 23 de octubre de 2026), Claude Code envía la conversación completa con cada solicitud, y cada uso de herramienta genera otra solicitud que lleva los resultados de la herramienta. El almacenamiento en caché de prompts relee el historial a una tarifa de caché más barata, pero los tokens siguen ahí.

Supongamos que el agente ejecuta npm test y obtiene un registro de 10,000 líneas. La documentación dice que ese tipo de registro puede tener decenas de miles de tokens. Supongamos 30,000 tokens. Hagas lo que hagas después, esos 30,000 tokens forman parte de la entrada del paso 11, el paso 12, el paso 13, y así sucesivamente hasta que hagas /clear o compactes. Y ahí está el problema: el registro es útil para un paso, y lo pagas durante treinta.

Solución 1: un hook PreToolUse que filtra la salida de pruebas#

La misma página de documentación sugiere hooks como preprocesamiento: un hook PreToolUse en Bash reescribe los comandos de prueba (npm test, pytest, go test) para que pasen por grep -A 5 -E '(FAIL|ERROR|error:)' | head -100. El agente entonces ve solo los fallos más unas pocas líneas de contexto, no 10,000 líneas de puntos verdes. La documentación dice que esto puede convertir decenas de miles de tokens en cientos.

Este es el script de esa página de documentación (consultada el 23 de octubre de 2026). Necesita jq. Crea la carpeta con mkdir -p ~/.claude/hooks, guarda el script como ~/.claude/hooks/filter-test-output.sh y ejecuta chmod +x sobre él:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'

if [[ "$cmd" =~ $pattern ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

Luego regístralo en ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }]
      }
    ]
  }
}

Para comprobar que funciona, abre /hooks dentro de Claude Code y busca la entrada PreToolUse, o empieza con claude --debug-file ./claude-debug.txt y pide al agente que ejecute npm test. Cuando el hook haya reescrito el comando, el archivo tiene una línea modified tool input keys con el campo command. Si las pruebas pasan, la salida está vacía, así que el agente recibe un éxito silencioso; ajusta el patrón si tu ejecutor imprime los fallos de otra manera.

Solución 2: context-mode para resultados de herramientas grandes#

Un hook solo cubre los comandos que puedes canalizar. Las capturas de página de Playwright o una lista de veinte issues de GitHub provienen de herramientas MCP. Eso es lo que ataca context-mode. Según su README (https://github.com/mksglu/context-mode, consultado el 23 de octubre de 2026; no muestra versión ni fecha), es un servidor MCP y plugin que mantiene la salida sin procesar de las herramientas fuera de la ventana de contexto, almacena el estado de la sesión en SQLite y enruta las llamadas a herramientas a través de hooks. Necesita Claude Code v1.0.33 o posterior, y su licencia es Elastic License 2.0, que no es una licencia de código abierto de OSI.

Instala dentro de Claude Code:

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

Reinicia o ejecuta /reload-plugins, luego verifica con /context-mode:ctx-doctor. La variante solo MCP, claude mcp add context-mode -- npx -y context-mode, añade las herramientas pero no tiene enrutamiento automático.

El proyecto reporta grandes reducciones: 315 KB se convierte en 5.4 KB (98%), una captura de página de 56 KB se convierte en 299 bytes, 986 KB se convierte en 62 KB. Esos son los números del propio autor: trátalos como el techo y mide en tu propia sesión con /context antes y después.

Lo que cuesta una sesión larga, con y sin filtrado#

Aquí está la aritmética de una sesión supuesta. Es una sesión de programación de 40 pasos con un contexto base promedio de 20,000 tokens, 500 tokens de salida por paso, y tres ejecuciones de pruebas, en los pasos 10, 20 y 30. Cada registro sin procesar es de 30,000 tokens; la versión filtrada es de 500.

• Un registro del paso 10 se reenvía en las 30 solicitudes posteriores: 30 × 30,000 = 900,000 tokens. Paso 20: 20 × 30,000 = 600,000. Paso 30: 10 × 30,000 = 300,000. Entrada extra: 900,000 + 600,000 + 300,000 = 1,800,000.
• Filtrado: (30 + 20 + 10) × 500 = 30,000 de entrada extra.
• Entrada base: 40 × 20,000 = 800,000. Salida: 40 × 500 = 20,000.
• Así que la sesión es 800,000 + 1,800,000 = 2,600,000 tokens de entrada sin filtrar y 800,000 + 30,000 = 830,000 filtrados, con 20,000 tokens de salida en ambos casos.

El cálculo cuenta cada token de entrada a la tarifa completa. El almacenamiento en caché reduce el número real, pero reduce ambos casos con la misma lógica. Los precios en vivo de MiniMax-M2.7 (MiniMaxAI/MiniMax-M2.7, contexto de 180K, hasta 8,192 tokens de salida), que es el modelo que se adapta a bucles de agente con mucha entrada como este, están en el gráfico a continuación.

Supuestos: 40 pasos, contexto base de 20,000 tokens, 500 tokens de salida por paso, tres ejecuciones de pruebas de 30,000 tokens (filtrado: 500).

En MiniMax-M2.7 la sesión cuesta $0.133 sin filtrar y $0.0445 filtrada, y en total, contando entrada y salida juntas, es más barata que el precio de referencia de OpenRouter. Aproximadamente dos tercios de la entrada en el caso sin filtrar son registros que el agente leyó una vez.

El punto no son los dólares exactos. Es que el filtro elimina alrededor de 1,770,000 de 2,600,000 tokens de entrada (2,600,000 − 830,000 = 1,770,000) en cualquier modelo, y un modelo más barato reduce el precio de cada token que queda.

Ejecuta Claude Code en un modelo de CheapTokens#

Claude Code habla el protocolo Anthropic Messages, y CheapTokens lo soporta. La URL base para Claude Code no tiene /v1. La configuración completa está en cómo conectar Claude Code a CheapTokens. La versión corta, con una clave de marcador de posición:

export ANTHROPIC_BASE_URL=https://api.cheaptokens.dev
export ANTHROPIC_AUTH_TOKEN=YOUR_CHEAPTOKENS_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude

Usa el id completo de la documentación; los nombres cortos de las tablas de precios no son aceptados por la API. Los precios de todos los modelos están en la página de precios. Para los otros hábitos que reducen una factura de Claude Code (/clear, /compact, /mcp, subagentes), consulta Cómo hacer Claude Code más barato. Para ver cómo se cuentan la entrada y la salida en una solicitud real, lee Cuántos tokens usa una solicitud de API.

Lista de verificación rápida#

1. Ejecuta /context en una sesión larga y observa qué está ocupando espacio.
2. Añade el hook de Bash para los comandos de prueba; confirma la reescritura en /hooks o el registro de depuración.
3. Si las herramientas MCP devuelven capturas grandes, prueba context-mode y compara /context antes y después.
4. /clear entre tareas no relacionadas, para que los registros antiguos dejen de viajar.