Comparativa de rastreadores de gasto de Claude Code

Qué lee realmente un rastreador de gasto de Claude Code

Cada rastreador de gasto de Claude Code lee una de tres fuentes de datos, y la fuente determina qué pregunta puede responder. Un analizador de registros lee los archivos de transcripción de las sesiones en su propio disco. Un dashboard 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í no coincidir, porque contabilizan cosas distintas.

Esta guía no vuelve a explicar los tokens. cómo cuenta Claude Code el uso de tokens cubre las entradas, las salidas, las escrituras de caché y las lecturas de caché, y ningún dashboard resulta muy ú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 rastreadores del gasto de Claude Code el mismo día

Ese día se publicaron tres rastreadores independientes del gasto de Claude Code. No eran tres versiones de la misma herramienta, y ahí está lo importante. Uno analizaba los archivos de sesión locales. Otro envolvía las pantallas de uso de la cuenta. El tercero era un backend de trazas alojado que se ejecuta en la propia infraestructura.

Aparecieron juntos porque el coste de una sesión de agente dejó de ser evidente. Un chat cuesta aproximadamente lo que se ve 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 de un contexto que nunca se escribió manualmente. En una suscripción, la cifra en dólares de la sesión que muestra Claude Code es una estimación que Anthropic indica que no es relevante para la facturación. La cifra importante es 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 diferencia.

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

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 reemplazados por -. Cada turno del asistente en ese archivo incluye el recuento de tokens de la solicitud. Un analizador de registros los suma y calcula su precio.

ccusage es la opción que usa 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 separa cada fila por modelo, que es la forma de descubrir que una tarde con Opus representa la mayor parte del uso de la semana. blocks agrupa por la ventana de cinco horas en la que se restablece una suscripción. session calcula los totales por conversación y daily --instances agrupa por proyecto para mostrar qué repositorio es más caro. 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 octubre de 2026 también lee otras CLI de agentes, incluidas Codex y OpenCode, lo que 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 del recuento 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 lo que todo lo que está leyendo es una estimación. Si paga tarifas negociadas, pricingOverrides dentro de defaults en un archivo de configuración ccusage.json reemplaza el precio de cada modelo.

Los mismos datos pueden alimentar el prompt. ccusage statusline imprime una línea compacta para la barra de estado de Claude Code, integrada en ~/.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 otro miembro del equipo: esas transcripciones están almacenadas en esos dispositivos. También faltan los datos antiguos, porque las transcripciones se eliminan después de 30 días de forma predeterminada mediante la configuración cleanupPeriodDays. Por tanto, el trimestre anterior desaparece si no lo 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. Esto se aplica a todas las herramientas de este tipo. También explica por qué un comando jq escrito manualmente sobre el JSONL es peor de lo que parece: los analizadores mantenidos siguen los cambios de formato, mientras que su comando de una línea informará de un número incorrecto con total confianza 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. El uso incluido en el límite de su plan Pro o Max no se factura por token. Por tanto, la cifra representa lo que sus tokens habrían costado según las tarifas públicas de la API. Mide la intensidad de su uso. No es su factura. La excepción son los créditos de uso: si los activa, el uso que supere el límite del plan se factura según las tarifas estándar de la API como un cargo independiente, y claude.ai muestra el gasto de ese mes en Settings > Usage. Si la pregunta real es qué plan elegir, esa comparación es un ejercicio independiente: consulte facturación de la API frente a una suscripción de Claude.

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

Claude Code incluye sus propios informes, pero la mayoría de los usuarios nunca los abre. Ejecute /usage dentro de una sesión. El bloque Session de la parte superior muestra los tokens por modelo y una cifra en dólares para la sesión actual. El cálculo se hace localmente a partir del número de tokens y de las tarifas de lista estándar, salvo que un administrador haya definido una tabla modelPricing en la configuración administrada. En ese caso, la línea Total cost indica at your organization's configured rates. En ambos casos, la cifra es una estimación que puede diferir de la factura. En los planes Pro o Max, Anthropic indica que no es relevante para la facturación porque ese uso está incluido en el plan. Los totales se restablecen cuando /clear inicia una conversación nueva.

En un plan Pro, Max, Team o Enterprise basado en puestos, la misma pantalla muestra qué proporción del límite del plan ha utilizado. Enterprise basado en el uso no tiene una asignación incluida que pueda agotarse, porque cada token se factura con las tarifas de la API. En estos planes, la pantalla también atribuye el uso reciente a skills, subagents, plugins y servidores MCP individuales 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 esta máquina, por lo que no se cuenta un segundo dispositivo. Cuando esa barra está vacía, en lugar de mostrar simplemente un nivel bajo, la pantalla indica que la ventana se ha cerrado, pero no cómo seguir trabajando. Qué hacer después de alcanzar el límite es una decisión independiente sobre el modelo, el contexto y el plan.

A partir de más de un desarrollador, los datos pasan a la cuenta. Una organización de API dispone de la página de uso de Console, de un panel de Claude Code con el gasto y las líneas aceptadas por miembro, y de 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, actualizado a diario. Sin embargo, el informe cubre el gasto de los créditos de uso: el uso incluido en la asignación del puesto no se mide en dólares. Enterprise añade una API de análisis. Los datos que verá dependen de cómo haya iniciado sesión cada desarrollador. Por eso, 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 a fecha de octubre de 2026 es una media cercana a $13 por desarrollador y día activo, y de $150 a $250 por desarrollador al mes. El 90% de los usuarios se mantiene por debajo de $30 por día activo. Considere esto un valor de referencia publicado a partir de implementaciones empresariales, no una predicción para su equipo. Ejecute un piloto con un grupo 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. Le indicarán que Opus fue el modelo más utilizado durante la mayor parte del martes. No le indicarán qué prompt, repositorio o 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 que se haya descontrolado. Para detectar 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: su propia pila de OpenTelemetry le indica qué prompt provocó la regresión

Claude Code emite métricas y eventos de OpenTelemetry cuando se configura una variable de entorno, y esta es la única opción que transmite datos por usuario sobre tokens y costes a un sistema bajo su control 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. Los nombres de los servidores MCP que haya configurado y de sus propios subagentes personalizados llegan como custom, a menos que configure OTEL_LOG_TOOL_DETAILS=1, que también añade los comandos de Bash y la entrada de las herramientas a los eventos de herramientas. Esto basta para responder preguntas que ningún panel puede resolver: qué parte de la factura corresponde a los subagentes y no a sus propias interacciones, si un servidor MCP duplicó sus tokens de entrada o si las lecturas de caché se desplomaron después de que alguien editara CLAUDE.md. El comportamiento de la caché suele ser la principal fuente de sorpresas, y cuándo la caché de prompts resulta rentable explica qué está observando.

Conviene hacer una corrección, porque este punto aparece en todos los debates sobre el tema. Langfuse es un buen backend de trazas autohospedado, y su ejecución en un VPS se explica en autohospedar Langfuse para el trazado de agentes. Su endpoint OTLP acepta únicamente trazas. De forma predeterminada, 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. La exportación de spans existe, pero es una función beta que permanece desactivada hasta que configure CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 y OTEL_TRACES_EXPORTER. La integración propia de Langfuse con Claude Code sigue otro enfoque: un hook Stop, o un plugin que lo instala, lee las transcripciones de la sesión después de cada respuesta y las convierte en trazas, por lo que comparte las limitaciones locales de un analizador de registros. Langfuse es la herramienta adecuada para los agentes que construya directamente sobre la API, donde su propio código crea cada span con su prompt, modelo y coste. Para obtener los totales de gasto de 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 collector 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 collector es accesible desde sus equipos y desde ningún otro lugar. La dirección situada delante del puerto es importante en este caso, porque los puertos publicados por Docker no están filtrados por ufw: consulte por qué los puertos publicados por Docker omiten ufw. La configuración del propio 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 collector 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 collector debe 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 usarlo. En cada equipo 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 una petición, espere al intervalo de exportación (10 segundos en este caso, 60 segundos de forma predeterminada) y pregunte a Prometheus qué ha aprendido:

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 exporter transforma los puntos en guiones bajos y añade la unidad, por lo que las cadenas exactas dependen de la versión del collector. Un resultado vacío significa que no ha llegado nada. Compruebe que el protocolo y el puerto coincidan, porque http/protobuf va al puerto 4318 y grpc va al puerto 4317, y una discrepancia falla silenciosamente. Ejecute claude --debug-file /tmp/claude-debug.log y busque en ese archivo las líneas [3P telemetry], que es donde Claude Code informa de los errores de exportación de OTel.

Para un solo equipo y sin servidor, omita todo lo anterior. Configure OTEL_METRICS_EXPORTER=prometheus y Claude Code expondrá directamente un endpoint de scraping en http://localhost:9464/metrics. Cuando prometheus es el único exporter indicado, Claude Code omite las unidades USD, tokens y s de las métricas exportadas para que el scraping mantenga un formato de texto válido de Prometheus. Los nombres de las métricas no cambian y una configuración que combina exporters, como otlp,prometheus, conserva las unidades.

Esta configuración implica una decisión de privacidad. De forma predeterminada, sólo salen del equipo los recuentos y los metadatos; no se exporta el texto de las peticiones ni la salida de las herramientas. OTEL_LOG_USER_PROMPTS=1 añade el texto de las peticiones a los eventos exportados y OTEL_LOG_TOOL_CONTENT=1 añade la salida de las herramientas a los spans de trazas, por lo que, en cuanto exporte cualquiera de esas señales, su equipo de telemetría contendrá código fuente y cualquier otro contenido que estuviera en el contexto. Active estas opciones deliberadamente y lea primero cómo mantener los secretos fuera del contexto del agente.

Seguimiento del gasto de ejecuciones mediante scripts y CI

Las ejecuciones no interactivas son las que más sorpresas causan, porque nadie está observando 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 un panel. Como cualquier cifra local, es una estimación del lado del cliente, y una ejecución que continúa una conversación con --continue o --resume informa del total de toda la conversación, incluidas las ejecuciones anteriores. Añada el valor a un archivo o envíelo como métrica al recopilador anterior. Es el seguimiento de gasto útil más económico disponible y requiere una llamada a jq por ejecución.

Modos de fallo y lo que 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. CLAUDE_CONFIG_DIR cambia esa ubicación y hay que indicársela al analizador. Si existen filas, pero se detienen aproximadamente hace un mes, es cleanupPeriodDays funcionando según lo previsto: de forma predeterminada, las transcripciones se eliminan después de 30 días.

Dos máquinas muestran totales diferentes. Es normal y no es un error. El desglose de /usage y cualquier analizador de registros leen únicamente 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 con las tarifas de lista estándar, salvo que configure tarifas contratadas: una tabla de modelPricing en la configuración administrada para /usage, o pricingOverrides para ccusage. En una suscripción, el uso incluido en el límite del plan no se factura por token, y sólo se facturan los créditos de uso. 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. Mientras la caché está activa, se aplica la tarifa de datos en caché. Cuando deja de estar activa, se aplica la tarifa completa de entrada. Por eso una pausa larga vuelve a procesar toda la conversación. Esto aparece como un número alto de tokens de entrada junto a un número bajo de tokens de salida, y los precios de tokens de entrada y salida explican por qué ambos 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. En un plan, la atribución de /usage muestra la proporción correspondiente a los subagentes en esta máquina, expresada como porcentaje. Para obtener detalles por solicitud, los datos de OTel los separan mediante el atributo query_source en claude_code.token.usage. Un analizador de registros mostrará el total, pero le obligará a deducir el resto.

FAQ

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

No. El uso incluido en el límite del plan de una suscripción no se factura por token. Por eso, un analizador de registros calcula el precio de los tokens con las tarifas estándar de lista de la API y muestra cuánto habría costado el mismo trabajo mediante la API. Es una buena medida relativa de la carga de un día y resulta útil para comparar proyectos o modelos entre sí. Para consultar el importe que debe pagar, la página de uso de Console cubre la facturación de la API y la página de facturación del plan cubre la suscripción. Si tiene activados los créditos de uso, el uso que supera el límite se factura con las tarifas estándar de la API, y claude.ai muestra ese gasto en Settings > Usage.

¿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, un uso de herramienta o una entrada de metadatos. CLAUDE_CONFIG_DIR mueve el directorio completo, 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 tanto, analícelo con una herramienta mantenida, no con un script propio.

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

No con la telemetría predeterminada. El endpoint OTLP de Langfuse acepta trazas, pero Claude Code exporta métricas y eventos de registro en lugar de spans de forma predeterminada. Por tanto, los datos no tienen dónde almacenarse. La exportación de spans es una función beta que debe activar, y la propia integración de Langfuse con Claude Code usa un hook Stop que convierte las transcripciones de sesión en trazas. Para obtener los totales de gasto, 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 directamente sobre la API, donde su propio código emite spans con 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 distinta. /usage y los analizadores de registros suman los recuentos de tokens de los archivos de sesión del equipo que está utilizando y después calculan el precio con las tarifas estándar de lista, salvo que haya tarifas contratadas configuradas, mediante modelPricing en los ajustes administrados para /usage o pricingOverrides para ccusage. Console muestra lo que se cobró realmente a su organización, en todos los equipos y todas las claves, después de aplicar los descuentos. Es normal que haya una diferencia. Una diferencia muy grande suele indicar que un segundo dispositivo, un ejecutor de CI u otro miembro del equipo está facturando en la misma cuenta.

¿Cómo puedo seguir 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 respuesta incluye un desglose por modelo y el ID de sesión. Registre ese valor por trabajo y obtendrá el gasto por canalización sin ningún agente, panel ni servicio adicional.