Comparativa de rastreadores de gasto de Claude Code

Qué lee realmente un rastreador de gasto de Claude Code

Todos los rastreadores de gasto de Claude Code leen una de tres fuentes de datos, y la fuente determina qué pregunta pueden responder. Un analizador de registros lee los archivos de transcripción de las sesiones almacenados en su propio disco. Un panel lee los registros de uso que Anthropic conserva para su cuenta o su organización. Un backend de métricas lee el flujo de OpenTelemetry (OTel) que Claude Code emite cuando se habilita. Las tres fuentes pueden ser correctas al mismo tiempo y aun así mostrar resultados distintos, porque cuentan cosas diferentes.

Esta guía no vuelve a explicar los tokens. cómo cuenta Claude Code el uso de tokens explica los tokens de entrada y salida, las escrituras en caché y las lecturas de caché, y ningún panel resulta útil hasta que esa parte está clara. La pregunta aquí es más concreta: para cada tipo de herramienta, qué puede ver y qué no puede ver nunca.

Por qué aparecieron tres herramientas de seguimiento del gasto de Claude Code el mismo día

Ese día se publicaron tres herramientas independientes para hacer un seguimiento del gasto de Claude Code. No eran tres versiones de la misma herramienta, y ese es el aspecto importante. Una analizaba los archivos de sesión locales. Otra envolvía las pantallas de uso de la cuenta. La tercera era un backend de trazas alojado que se ejecuta por cuenta propia.

Aparecieron juntas porque el coste de una sesión de agente dejó de ser evidente. Un chat cuesta aproximadamente lo que se muestra en pantalla. Un agente lee veinte archivos, ejecuta la suite de pruebas y vuelve a enviar toda la conversación en cada turno, por lo que la factura depende del contexto que nunca se escribió manualmente. En una suscripción no aparece ninguna cifra en dólares, sino una barra de uso que se vacía más rápido unos días que otros. Cada una de las tres herramientas cubre una parte distinta de esa carencia.

Forma 1: un analizador de registros local muestra cuánto costó el día de hoy

Claude Code almacena cada conversación como JSON Lines (JSONL) en ~/.claude/projects/<project>/<session-id>.jsonl, donde <project> es la ruta del directorio de trabajo con los caracteres no alfanuméricos sustituidos por -. Cada intervención del asistente en ese archivo incluye el recuento de tokens de su solicitud. Un analizador de registros suma esos recuentos y calcula el precio.

ccusage es la opción que utiliza la mayoría. No requiere instalación:

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily calcula los totales por fecha. --breakdown divide cada fila por modelo. Así puede comprobar que una tarde con Opus representa la mayor parte del uso de la semana. blocks agrupa los datos según la ventana de cinco horas en la que se restablece la suscripción. session calcula los totales por conversación, y --instances agrupa por proyecto para mostrar qué repositorio tiene el mayor coste. Añada --since y --until para limitar el intervalo, y ejecute npx ccusage@latest daily --help para consultar el formato de fecha que espera su versión. Desde agosto de 2026 también lee otras CLI de agentes, como Codex y OpenCode. Esto resulta útil para compararlas.

Los precios proceden de una tabla de precios de modelos, y la herramienta tiene tres modos de cálculo de costes. --mode auto usa el valor costUSD que Claude Code escribió en el archivo cuando está disponible, y calcula el coste a partir de los recuentos de tokens cuando no lo está. --mode calculate siempre calcula el coste a partir de los tokens e ignora cualquier coste registrado. --mode display muestra sólo los costes registrados e imprime $0.00 en las filas que no tienen ninguno. Si un total parece incorrecto, ejecute el mismo informe con calculate y después con display. Una diferencia grande entre ambos indica que la mayoría de las entradas no tienen un coste registrado. Por tanto, todo lo que está leyendo es una estimación.

Los mismos datos pueden alimentar su prompt. ccusage statusline imprime una línea compacta para la barra de estado de Claude Code, conectada mediante ~/.claude/settings.json como cualquier otro comando de línea de estado. Consulte crear una línea de estado de Claude Code para ver el bloque de configuración y los campos que recibe.

Un analizador de registros no puede ver nada que no haya ocurrido en este equipo. Un segundo portátil, una sesión en claude.ai o el trabajo de un compañero están en los discos correspondientes. También faltan los datos antiguos, porque las transcripciones se eliminan después de 30 días de forma predeterminada mediante el ajuste cleanupPeriodDays. Por tanto, los datos del último trimestre desaparecen si no los archivó.

Existe otro riesgo, de carácter estructural. La documentación de Anthropic indica que el formato de las entradas es interno de Claude Code y cambia entre versiones. Por eso, los scripts que analizan directamente estos archivos pueden dejar de funcionar con cualquier versión nueva. Esto se aplica a todas las herramientas de este tipo. También explica por qué un jq escrito manualmente sobre el JSONL es peor de lo que parece: los analizadores mantenidos siguen los cambios de formato, mientras que su one-liner mostrará una cifra incorrecta con seguridad aparente el día que cambie el nombre de un campo.

Por último, la cifra en dólares requiere una aclaración cuando se usa una suscripción. En Pro o Max no se factura por token. Por tanto, la cifra representa lo que habrían costado sus tokens según las tarifas públicas de la API. Mide la intensidad de su uso. No es su factura. Si la pregunta real es qué plan debe elegir, esa comparación requiere un análisis independiente: consulte facturación de la API frente a una suscripción de Claude.

Forma 2: las pantallas de uso integradas muestran qué modelo consumió el presupuesto

Claude Code incluye sus propios informes, pero la mayoría de las personas nunca los abre. Ejecute /usage dentro de una sesión. El bloque Session de la parte superior muestra los tokens por modelo y un importe en dólares para la sesión actual. El importe se calcula localmente a partir del número de tokens y de las tarifas de lista estándar. No refleja descuentos ni precios promocionales, por lo que puede diferir de la factura. Los totales se restablecen cuando /clear inicia una conversación nueva.

En los planes Pro, Max, Team o Enterprise, la misma pantalla muestra cuánto del límite del plan ha utilizado. También atribuye el uso reciente a skills, subagents, plugins y servidores MCP individuales, expresado como porcentaje del total. Señala los comportamientos que representan el 10% o más del uso reciente, como un contexto largo o fallos de caché. Pulse d o w para cambiar entre las últimas 24 horas y los últimos 7 días. Estas cifras son aproximadas y se calculan a partir del historial de sesiones local de este equipo, por lo que no incluyen un segundo dispositivo. Cuando la barra está vacía, en lugar de simplemente baja, la pantalla indica que la ventana se ha cerrado, pero no cómo continuar trabajando. Qué hacer después de alcanzar el límite es una decisión independiente sobre el modelo, el contexto y el plan.

Cuando hay más de un desarrollador, las cifras pasan a la cuenta. Una organización de API obtiene la página de uso de Console, un panel de Claude Code con el gasto y las líneas aceptadas por miembro, y una API de análisis de Claude Code que devuelve las mismas métricas diarias por usuario mediante una clave de administrador. Los planes Team y Enterprise incluyen un informe de gasto en la consola de administración, con exportación CSV y actualización diaria. Enterprise también añade una API de análisis. Lo que se muestra depende de cómo haya iniciado sesión cada desarrollador, por lo que una organización mixta debe consultar dos informes y sumar los datos manualmente.

Para dimensionar un presupuesto, la cifra publicada en la documentación de costes de Anthropic en agosto de 2026 es un promedio cercano a $13 por desarrollador y día activo, y de $150 a $250 por desarrollador y mes. El 90% de los usuarios se mantiene por debajo de $30 por día activo. Considere este valor un parámetro publicado a partir de implementaciones empresariales, no una predicción para su equipo. Ejecute un piloto y mida los resultados antes de extrapolar.

Los paneles no pueden mostrar nada con un nivel de detalle inferior al día y la persona. Indicarán que Opus concentró la mayor parte del uso del martes. No indicarán qué prompt, qué repositorio o qué tarea de CI lo provocó. Además, presentan retraso porque los informes de la organización se actualizan a diario. Por tanto, sirven para revisar el uso, no para detectar esta tarde un agente descontrolado. Para detectar y contener ese comportamiento hacen falta límites, no informes. Ese es el tema de mantener acotados los costes de los agentes en un VPS.

Forma 3: tu propia pila de OpenTelemetry te indica qué prompt provocó la regresión

Claude Code emite métricas y eventos de OpenTelemetry después de configurar una variable de entorno. Es la única opción que transmite datos de tokens y costes por usuario a un sistema que controlas, casi en tiempo real. Las métricas incluyen claude_code.cost.usage en USD, claude_code.token.usage en tokens, claude_code.session.count y claude_code.active_time.total.

La métrica de tokens es la más interesante por sus atributos. Cada punto de datos incluye type, que puede ser input, output, cacheRead o cacheCreation, además de model y query_source, que puede ser main, subagent o auxiliary. También incluye agent.name, skill.name, mcp_server.name y mcp_tool.name. Esto basta para responder preguntas que ningún panel puede resolver: cuánto de la factura corresponde a subagentes en lugar de tus propios turnos, si un servidor MCP duplicó los tokens de entrada y si las lecturas de caché disminuyeron después de que alguien editara CLAUDE.md. El comportamiento de la caché suele ocultar la sorpresa, y cuándo la caché de prompts se amortiza explica qué estás observando.

Conviene hacer una corrección, porque aparece en todos los debates sobre este tema. Langfuse es un buen backend de trazas autohospedado, y su ejecución en un VPS se explica en autohospedar Langfuse para el seguimiento de agentes. Su endpoint OTLP sólo acepta trazas. Claude Code exporta métricas y eventos de registro, no spans, por lo que apuntar OTEL_EXPORTER_OTLP_ENDPOINT a Langfuse deja el proyecto vacío y no produce ningún error útil. Langfuse es la herramienta adecuada para los agentes que construyes directamente sobre la API, donde tu propio código crea cada span con su prompt, modelo y coste. Para la CLI de Claude Code, la opción adecuada es un almacén de métricas.

Configurar el seguimiento del gasto de Claude Code en un VPS propio

Bastan dos servicios: un colector que reciba las métricas y Prometheus para almacenarlas. Mantenga ambos fuera de Internet pública, porque un puerto OTLP abierto acepta escrituras de cualquiera que lo encuentre. Escriba /opt/ccmetrics/compose.yaml:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 es la dirección del servidor dentro de un túnel WireGuard, por lo que el colector es accesible desde sus máquinas y desde ningún otro lugar. La dirección situada delante del puerto es importante aquí, porque los puertos publicados por Docker no están filtrados por ufw: consulte por qué los puertos publicados por Docker evitan ufw. La configuración del túnel se explica en una VPN WireGuard en su propio VPS.

/opt/ccmetrics/collector.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml. El puerto 8889 nunca se publica en el host, porque Prometheus accede al colector a través de la red de Compose mediante el nombre del servicio:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

El registro del colector debería terminar con Everything is ready. Begin running and processing data.. Si el registro se detiene por un error de configuración, significa que el YAML no se pudo analizar y el contenedor se reiniciará en un bucle.

Ahora configure Claude Code para que lo use. En cada máquina que ejecute Claude Code, añada esto a ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

Inicie una sesión, envíe un prompt, espere al intervalo de exportación (10 segundos en este caso, 60 segundos de forma predeterminada) y pregunte a Prometheus qué datos ha recibido:

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

Debería obtener varios nombres que comiencen por claude_code_. El exportador sustituye los puntos por guiones bajos y añade la unidad, por lo que las cadenas exactas dependen de la versión del colector. Un resultado vacío significa que no ha llegado nada. Compruebe que el protocolo y el puerto coincidan, porque http/protobuf usa el puerto 4318 y grpc usa el puerto 4317; una discrepancia falla sin mostrar información clara. Ejecute claude --debug y el registro de depuración mostrará los errores de exportación de OTel.

Si sólo necesita una máquina y no quiere usar un servidor, omita todo lo anterior. Configure OTEL_METRICS_EXPORTER=prometheus y Claude Code expondrá un endpoint de scraping en http://localhost:9464/metrics. Cuando prometheus sea el único exportador de la lista, Claude Code omitirá las unidades USD, tokens y s de los nombres de las métricas para que el scraping mantenga un formato de texto válido para Prometheus.

Esta configuración implica una decisión de privacidad. De forma predeterminada, sólo salen de la máquina los recuentos; no se envían el texto de los prompts ni la salida de las herramientas. OTEL_LOG_USER_PROMPTS=1 y OTEL_LOG_TOOL_CONTENT=1 cambian este comportamiento. En ese caso, el servidor de métricas contiene código fuente y cualquier otro dato incluido en el contexto. Active estas opciones de forma deliberada y lea primero cómo evitar secretos en el contexto del agente.

Seguimiento del gasto de ejecuciones mediante scripts y CI

Las ejecuciones no interactivas son las que suelen causar sorpresas, porque nadie observa la pantalla. claude -p con --output-format json informa del coste de esa ejecución en su carga útil de resultados:

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

La carga útil incluye total_cost_usd y un desglose por modelo, por lo que un trabajo de CI puede registrar su propio gasto sin usar ningún panel. Añada el valor a un archivo o envíelo como métrica al colector anterior. Este es el seguimiento de gasto útil más económico disponible y requiere una llamada a jq por ejecución.

Modos de fallo y qué verá

El informe está vacío. npx ccusage@latest daily no muestra ninguna fila porque no está leyendo la ubicación donde Claude Code escribe los datos. CLAUDE_CONFIG_DIR cambia esa ubicación y hay que indicársela al analizador. Si hay filas, pero se detienen aproximadamente un mes atrás, es cleanupPeriodDays funcionando según lo previsto: las transcripciones se eliminan después de 30 días de forma predeterminada.

Dos máquinas muestran totales diferentes. Es lo esperado y no es un error. Tanto /usage como cualquier analizador de registros sólo leen el historial de sesiones local, por lo que el uso de otro dispositivo o de claude.ai no aparece en ninguno de los dos.

El total local no coincide con la factura. Las cifras locales se calculan a partir del recuento de tokens y las tarifas estándar de lista. No tienen en cuenta los precios promocionales ni un descuento contratado. Además, en una suscripción los tokens no se facturan individualmente. La página de uso de Console es la fuente autorizada para la facturación de la API.

El coste aumentó aunque hizo el mismo trabajo. Revise primero las columnas de caché. Una sesión larga vuelve a enviar todo su historial en cada turno. Se factura con la tarifa de caché mientras la caché está activa y con la tarifa completa de entrada cuando deja de estarlo. Por eso, una pausa larga vuelve a procesar toda la conversación. Esto aparece como una cifra de entrada grande junto a una cifra de salida pequeña, y la tarificación de tokens de entrada frente a la de salida explica por qué ambas evolucionan de forma independiente.

Un día con subagentes parece imposible. Cada subagente ejecuta su propia ventana de contexto, por lo que el uso de tokens aumenta según cuántos se ejecutaron y cuánto duró cada uno. Sólo los datos de OTel los separan mediante el atributo query_source en claude_code.token.usage. Un analizador de registros mostrará el total y le obligará a hacer suposiciones.

FAQ

¿ccusage muestra lo que realmente se me factura en un plan Max?

No. En una suscripción no se factura por token, por lo que un analizador de registros asigna a los tokens las tarifas estándar de lista de la API y muestra cuánto habría costado el mismo trabajo mediante la API. Es una medida relativa útil para saber la intensidad de un día y comparar proyectos o modelos entre sí. Para consultar el importe que debe pagar, la página de uso de Console muestra la facturación de la API y la página de facturación del plan muestra la facturación de la suscripción.

¿Dónde almacena Claude Code los archivos de sesión que leen estas herramientas?

En ~/.claude/projects/<project>/<session-id>.jsonl, donde <project> es la ruta del directorio de trabajo con los caracteres no alfanuméricos reemplazados por -. Cada línea es un objeto JSON correspondiente a un mensaje, uso de una herramienta o entrada de metadatos. CLAUDE_CONFIG_DIR mueve todo el directorio, y cleanupPeriodDays en settings.json controla la retención de 30 días. Anthropic documenta el formato de las entradas como interno y sujeto a cambios entre versiones, por lo que debe analizarlo con una herramienta mantenida y no con un script propio.

¿Puedo enviar la telemetría de Claude Code a Langfuse?

No directamente. El endpoint OTLP de Langfuse acepta trazas, mientras que Claude Code exporta métricas y eventos de registro en lugar de spans, por lo que esos datos no tienen dónde almacenarse. Envíe las métricas de Claude Code a un colector de OpenTelemetry y almacénelas en Prometheus. Use Langfuse para los agentes que cree mediante la API, donde su propio código emite spans que contienen el prompt, el modelo y el coste.

¿Por qué mis cifras locales no coinciden con la página de uso de Console?

Porque se calculan de forma diferente. /usage y los analizadores de registros suman los recuentos de tokens de los archivos de sesión del equipo en el que está trabajando y después aplican las tarifas estándar de lista. Console informa de lo que se cobró realmente a su organización, en todos los equipos y todas las claves, después de aplicar los descuentos correspondientes. Es normal que haya una diferencia. Una diferencia muy grande suele indicar que otro dispositivo, un ejecutor de CI u otro miembro del equipo está facturando en la misma cuenta.

¿Cómo sigo el coste de una ejecución de claude -p en CI?

Ejecútela con --output-format json y lea total_cost_usd del resultado, por ejemplo con claude -p "..." --output-format json | jq '.total_cost_usd'. La misma carga útil incluye un desglose por modelo y el ID de sesión. Registre ese valor por trabajo para obtener el gasto por canalización sin usar ningún agente, panel ni servicio adicional.