Controlar tokens y coste en Claude Code: statusline, /usage y dashboards

Claude Code ya trae casi todo lo necesario para saber cuánto gastas: el comando /usage (con /cost y /stats como alias), una statusline que recibe por stdin un JSON con coste, ventana de contexto y límites del plan, y el diálogo Account & usage en la extensión de VS Code. Lo que no trae de serie es histórico largo ni un dashboard de equipo: para eso están ccusage en local y la exportación OpenTelemetry hacia Grafana o el backend que uses. Todo lo que sigue está comprobado contra la documentación oficial y el changelog a 7 de octubre de 2026 (Claude Code 2.1.292).

/usage: lo que ves sin instalar nada

/usage muestra el coste de la sesión, los límites del plan y estadísticas de actividad. /cost y /stats siguen funcionando, pero hoy son alias del mismo comando, según la referencia de comandos. La pantalla tiene varias partes:

• Bloque Session: Total cost, duración de API y de reloj, líneas añadidas y eliminadas, y tokens por modelo (entrada, salida, lectura y escritura de caché). El importe se calcula en local a precio de lista, salvo que tu organización haya fijado tarifas propias con el ajuste gestionado modelPricing. Es una estimación: la cifra de facturación está en la página de uso de la Claude Console. Se reinicia a 0 cuando /clear abre una sesión nueva.
• Línea Prompt cache (main) (v2.1.251 o posterior): peticiones, porcentaje de tokens de entrada servidos desde caché, fallos de caché y si la caché sigue caliente.
• Desglose del plan (Pro, Max, Team y Enterprise): barras de uso con su hora de reinicio, reparto del consumo reciente entre skills, subagentes, plugins y servidores MCP concretos (el coste por servidor MCP lo analiza qué servidores MCP sobreviven a la prueba de tokens), avisos cuando un comportamiento como el contexto largo o los fallos de caché supone el 10 % o más del uso reciente, y las tareas /loop que más consumen. Con d y w cambias entre últimas 24 horas y últimos 7 días.

Dos matices de la documentación de costes: si estás en Pro o Max, el importe del bloque Session no es lo que pagas (el uso dentro de los límites del plan va incluido en la suscripción; el que pase a créditos de uso se cobra aparte), y el desglose se calcula con el historial local de esa máquina, así que no incluye lo que hagas en otro equipo ni en claude.ai. Para ver qué ocupa la ventana de contexto en este momento, el comando es /context.

Límites del plan: qué se agota y cuándo

Al agotar la ventana aparece You've hit your session limit o You've hit your weekly limit con la hora de reinicio; cambiar de modelo no lo arregla porque esos límites son comunes a todos los modelos. Con You've hit your Opus limit sí puedes seguir con otro modelo vía /model (referencia de errores). Si quieres seguir pasado el límite, /usage-credits abre la configuración de créditos de uso o, en Team y Enterprise sin permisos de facturación, envía la petición a tus administradores. En modo no interactivo, claude -p acepta --max-budget-usd para cortar al llegar a un importe estimado.

La caché de prompts explica buena parte de las diferencias de gasto entre sesiones parecidas. Según la tabla de precios de la API, una lectura de caché cuesta 0,1 veces el precio de entrada base en la mayoría de modelos, 0,05 en Opus 5.5 y 0,025 en Fable 5.1 y Mythos 5.1. La caché caduca: dura una hora en suscripción, baja a cinco minutos cuando ya consumes créditos de uso y son cinco minutos por defecto con clave de API o proveedor cloud. El primer mensaje después de una pausa más larga vuelve a procesar todo el contexto sin caché.

Statusline personalizada: configuración y JSON de entrada

La statusline es una fila al pie de Claude Code que ejecuta el comando que configures y muestra lo que imprima por stdout. Se ejecuta en local y no consume tokens. La forma rápida de crearla es /statusline con una descripción en lenguaje natural (por ejemplo, /statusline muestra modelo, coste y porcentaje de contexto): Claude Code genera el script en ~/.claude/ y actualiza tu configuración. Para hacerlo a mano, añade el campo statusLine a ~/.claude/settings.json o a la configuración del proyecto:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

Según la referencia de ajustes, además de type y command solo hay tres campos opcionales: padding (espaciado horizontal en caracteres), refreshInterval (vuelve a ejecutar el comando cada N segundos, mínimo 1) y hideVimModeIndicator. No hay un campo timeout, aunque circulen ejemplos que lo usan.

El script se ejecuta al empezar o reanudar la sesión, con cada respuesta nueva del asistente, al terminar /compact, al cambiar el modo de permisos o vim, cuando una ventana de rate_limits llega a su resets_at y cuando caduca la caché. Las actualizaciones se agrupan con un debounce de 300 ms, y si llega otra mientras el script sigue corriendo, Claude Code cancela la ejecución en curso (documentación de la statusline).

Campos del JSON útiles para controlar el gasto

El JSON trae más campos (directorio, rama, PR abierta, worktree, sesión); la lista completa y el esquema están en la documentación de la statusline. Los que pueden faltar hay que leerlos con valor por defecto: // 0 o // empty en jq.

Script de ejemplo con jq

Este script muestra modelo, coste, contexto, uso de las ventanas de 5 horas y 7 días con la hora de reinicio de cada una (día y hora en la semanal), y el porcentaje de entrada servido desde caché. Necesita jq instalado. Guárdalo como ~/.claude/statusline.sh y dale permisos con chmod +x ~/.claude/statusline.sh:

#!/bin/bash
# ~/.claude/statusline.sh: modelo, coste, contexto, cuota y caché
export LC_ALL=C   # punto decimal en printf aunque el sistema use es_ES
input=$(cat)

# Epoch a hora local: GNU date (Linux, Git Bash) o BSD date (macOS)
hora() { date -d "@$1" +"$2" 2>/dev/null || date -r "$1" +"$2"; }

MODEL=$(echo "$input" | jq -r '.model.display_name // "?"')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
CTX=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
FIVE_RESET=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
WEEK_RESET=$(echo "$input" | jq -r '.rate_limits.seven_day.resets_at // empty')
HIT=$(echo "$input" | jq -r '.prompt_cache.hit_ratio // empty')

LINE="[$MODEL] \$$(printf '%.2f' "$COST") | ctx ${CTX}%"
if [ -n "$FIVE_H" ]; then
  LINE="$LINE | 5h $(printf '%.0f' "$FIVE_H")%"
  [ -n "$FIVE_RESET" ] && LINE="$LINE ($(hora "$FIVE_RESET" %H:%M))"
fi
if [ -n "$WEEK" ]; then
  LINE="$LINE | 7d $(printf '%.0f' "$WEEK")%"
  [ -n "$WEEK_RESET" ] && LINE="$LINE ($(hora "$WEEK_RESET" '%d/%m %H:%M'))"
fi
[ -n "$HIT" ] && LINE="$LINE | cache $(awk -v h="$HIT" 'BEGIN { printf "%.0f", h * 100 }')%"
echo "$LINE"

La línea export LC_ALL=C no es decorativa: con el sistema en es_ES.UTF-8, el printf de bash espera coma decimal, rechaza 1.8734 con invalid number y la cifra sale mal. Para probarlo antes de configurarlo, pásale un JSON con la forma documentada:

cat > ejemplo.json <<'EOF'
{
  "model": { "id": "claude-opus-5-5", "display_name": "Opus" },
  "cost": { "total_cost_usd": 1.8734, "total_duration_ms": 2700000 },
  "context_window": { "context_window_size": 200000, "used_percentage": 42.7 },
  "rate_limits": {
    "five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
    "seven_day": { "used_percentage": 41.2, "resets_at": 1738857600 }
  },
  "prompt_cache": { "warm": true, "hit_ratio": 0.91 }
}
EOF
~/.claude/statusline.sh < ejemplo.json
# [Opus] $1.87 | ctx 42% | 5h 24% (17:00) | 7d 41% (06/02 17:00) | cache 91%

Las horas de reinicio salen en la zona horaria local (en el ejemplo, horario peninsular). Con una clave de API no llega rate_limits y la salida se queda en [Opus] $1.87 | ctx 42% | cache 91%.

Windows y fallos habituales

• En Windows, Claude Code ejecuta la statusline con Git Bash si está instalado y, si no, con PowerShell. Escribe las rutas de command con barras /: Git Bash interpreta las barras invertidas como escapes y el comando falla sin aviso. Para un script de PowerShell, usa powershell -NoProfile -File C:/Users/usuario/.claude/statusline.ps1.
• Si el script termina con código distinto de 0 o no imprime nada, la statusline se queda en blanco. claude --debug registra su stderr.
• La statusline no se ejecuta hasta que aceptas la confianza del directorio, y si disableAllHooks está activo fuera de la configuración gestionada o tu organización activa allowManagedHooksOnly, solo se ejecuta la statusline definida en la configuración gestionada.
• Si /context marca más que la statusline, es normal: la statusline usa los recuentos de la última respuesta y /context añade una estimación de lo enviado después.

ccusage: histórico, bloques de 5 horas y burn rate

El JSON de la statusline solo describe la sesión actual. Para ver el gasto por día, semana, mes o sesión, la herramienta de referencia es ccusage (versión 20.0.26 en npm a esta fecha): lee los datos de uso que los agentes de código guardan en local y calcula costes con sus tablas de precios. Además de Claude Code, lee Codex, OpenCode, Amp, Gemini CLI, GitHub Copilot CLI y otra docena de herramientas.

npx ccusage@latest claude daily              # Claude Code, por día
npx ccusage@latest claude daily --instances  # agrupado por proyecto
npx ccusage@latest blocks                    # ventanas de 5 horas de Claude Code
npx ccusage@latest daily --json              # todas las fuentes, en JSON

Su subcomando statusline (en beta según su guía) añade a la statusline lo que el JSON nativo no da: coste del día en todas las sesiones, coste y tiempo restante del bloque de 5 horas activo, y burn rate en dólares por hora. Por defecto usa precios en caché sin conexión, y con --cost-source eliges entre el coste que calcula Claude Code (cc), el suyo (ccusage) o ambos (both):

{
  "statusLine": {
    "type": "command",
    "command": "bun x ccusage statusline --visual-burn-rate emoji",
    "padding": 0
  }
}

La guía de ccusage propone bun x como opción recomendada y npx -y ccusage statusline como alternativa si no usas Bun. Un límite que afecta a cualquier herramienta de histórico local: Claude Code borra las transcripciones de sesión con más de 30 días en un barrido al iniciar sesión. Si quieres más histórico, sube cleanupPeriodDays en settings.json (referencia de ajustes).

Dashboard de uso de tokens: qué opción te sirve

"Dashboard" puede significar cosas muy distintas según trabajes solo o administres un equipo. Estas son las opciones que existen hoy, de menos a más infraestructura:

Las dos analíticas oficiales están en claude.ai/analytics/claude-code (Team y Enterprise) y platform.claude.com/claude-code (Console), según la documentación de analítica. En Team y Enterprise, el dashboard no da tokens por persona: para eso están el informe de gasto o OpenTelemetry.

Dentro de VS Code

En la extensión oficial (anthropic.claude-code), /usage abre el diálogo Account & usage desde la versión 2.1.120. Con un plan de claude.ai muestra las barras de cada límite con el tiempo hasta el reinicio, los avisos de comportamientos que suponen el 10 % o más del uso reciente y las tablas de atribución por skill, subagente, plugin y servidor MCP (añadidas en 2.1.174), con selector Day y Week. Con clave de API o proveedor cloud muestra el coste y los tokens de la sesión (2.1.277). Desde 2.1.257, la lista de sesiones del panel lateral tiene una sección ACCOUNT & USAGE plegable con un medidor de uso y un enlace al diálogo completo. Fuentes: documentación de la extensión y changelog.

La statusline personalizada es parte de la interfaz de terminal y la documentación de la extensión no la menciona en el panel gráfico. Si la quieres dentro del editor, activa el ajuste claudeCode.useTerminal (interfaz estilo CLI) o ejecuta claude en el terminal integrado. Más contexto sobre combinar agentes en el editor en VS Code multi-agente: Copilot, Claude y Codex.

Si prefieres el coste en la barra de estado de VS Code, hay extensiones de la comunidad. Estas dos están publicadas en el Marketplace con su ID exacto (datos del Marketplace a 7 de octubre de 2026):

No son de Anthropic: sus importes son estimaciones de cada autor, igual que los de ccusage. Revisa qué datos leen y si hacen peticiones a tu cuenta antes de instalarlas.

Equipos: métricas con OpenTelemetry

OpenTelemetry es la única opción que funciona con cualquier forma de acceso (suscripción, Console o proveedor cloud) y envía tokens y coste por usuario a tu propio stack casi en tiempo real. Las métricas y los eventos de log están documentados sin etiqueta beta; solo las trazas siguen en beta. Se activa con variables de entorno (documentación de monitorización):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp        # otlp, prometheus, console o none
export OTEL_LOGS_EXPORTER=otlp           # otlp, console o none
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc  # obligatorio: no hay protocolo por defecto
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer tu-token"
claude

Las métricas se exportan cada 60 segundos y los logs cada 5 por defecto (OTEL_METRIC_EXPORT_INTERVAL y OTEL_LOGS_EXPORT_INTERVAL, en milisegundos). Para un dashboard personal sin colector, OTEL_METRICS_EXPORTER=prometheus expone las métricas en http://localhost:9464/metrics para que Prometheus las recoja. Para comprobar que llegan datos, busca claude_code.session.count, que se emite al iniciar sesión.

Las métricas de tokens y coste llevan los atributos model, query_source (main, subagent o auxiliary), effort, y agent.name, skill.name, plugin.name y mcp_server.name cuando aplican. Por defecto, los nombres de subagentes propios y servidores MCP configurados por el usuario salen como custom, y los de skills y plugins de terceros como third-party; OTEL_LOG_TOOL_DETAILS=1 muestra los nombres reales. Todas incluyen atributos estándar como session.id, user.account_uuid, user.email (si hay sesión iniciada) y terminal.type. Para segmentar por equipo, añade claves propias con OTEL_RESOURCE_ATTRIBUTES, y por repositorio, activa OTEL_METRICS_INCLUDE_REPOSITORY=true (v2.1.269 o posterior).

Tres puntos que conviene saber antes de desplegarlo:

• Dónde poner las variables: en la configuración gestionada (bloque env) para toda la organización, o en la shell o ~/.claude/settings.json de cada persona. Claude Code ignora las variables de exportación OTel en .claude/settings.json y .claude/settings.local.json del repositorio, así que un repo no puede activar la telemetría ni redirigirla.
• Privacidad: por defecto no se registra el texto de los prompts ni de las respuestas, los argumentos de las herramientas, el contenido de las herramientas en las trazas ni los cuerpos de la API. Cada cosa tiene su variable: OTEL_LOG_USER_PROMPTS, OTEL_LOG_ASSISTANT_RESPONSES, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT (solo con trazas) y OTEL_LOG_RAW_API_BODIES. Esta última vuelca las peticiones y respuestas completas de la API, con todo el historial de la conversación, así que equivale a activar todas las anteriores (seguridad y privacidad).
• El coste es aproximado: la propia documentación remite a la Console o al proveedor cloud para la facturación oficial. Si tu organización tiene tarifas pactadas, el ajuste gestionado modelPricing hace que /usage, la statusline y la métrica de coste usen esas tarifas.

Para no diseñar los paneles desde cero, en el catálogo de Grafana hay un dashboard publicado por la comunidad, Claude Code Metrics (Prometheus), ID 25255, que consume estas métricas y muestra coste, tokens, sesiones, tiempo activo, commits, PR, ratio de caché y rankings por usuario, modelo y sesión. No lo publica Anthropic.

Como referencia de presupuesto, la documentación de costes cifra el gasto medio en despliegues de empresa en unos 13 dólares por desarrollador y día activo, entre 150 y 250 dólares al mes, con el 90 % de los usuarios por debajo de 30 dólares por día activo. Son medias de Anthropic, no un objetivo: la propia página recomienda medir con un grupo piloto antes de extrapolar.

Preguntas frecuentes

¿Sigue existiendo el comando /cost en Claude Code?

Sí, pero como alias de /usage, igual que /stats. Los tres abren la misma pantalla con el coste de la sesión, los límites del plan y las estadísticas de actividad.

¿Por qué no aparece rate_limits en el JSON de mi statusline?

El objeto rate_limits solo llega a suscriptores Pro y Max de claude.ai, o detrás de un Claude apps gateway con límite de gasto, y solo después de la primera respuesta de la API en la sesión. Con clave de API no aparece. Cada ventana puede faltar por separado, así que léela con // empty en jq.

¿El coste que muestran /usage y la statusline es lo que voy a pagar?

No exactamente. Es una estimación calculada en local a precio de lista, salvo que tu organización haya configurado modelPricing. Con clave de API, la cifra de facturación está en la página de uso de la Claude Console. En Pro y Max, el uso dentro de los límites del plan va incluido en la suscripción; si activas los créditos de uso, lo que consumas por encima del límite se cobra aparte.

¿La statusline gasta tokens?

No. El script se ejecuta en local con los datos que Claude Code ya tiene y no hace llamadas a la API.

¿Cuánto histórico de uso puedo ver en local?

Claude Code borra las transcripciones de sesión con más de 30 días por defecto, y herramientas como ccusage solo pueden leer lo que queda en disco. Puedes ampliar el plazo con cleanupPeriodDays en settings.json; para un histórico de equipo independiente de cada máquina, usa OpenTelemetry.