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 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 activa. Las tres fuentes pueden ser correctas al mismo tiempo y aun así no coincidir, porque contabilizan cosas diferentes.

Esta guía no vuelve a explicar los tokens. cómo Claude Code contabiliza el uso de tokens explica las entradas, las salidas, las escrituras en caché y las lecturas de caché, y ningún panel 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 de gasto de Claude Code el mismo día

Ese mismo día se publicaron tres rastreadores de gasto distintos para Claude Code. No eran tres versiones de la misma herramienta, y esa es la parte 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 por cuenta propia.

Aparecieron juntos porque el coste de una sesión de agente dejó de ser evidente. Un chat cuesta aproximadamente lo que se puede ver 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 hay ninguna cifra en dólares, sino sólo 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 reemplazados por -. Cada turno del asistente en ese archivo incluye el recuento de tokens de su 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. Así puede comprobar que una tarde con Opus representa la mayor parte de la semana. blocks agrupa por la ventana de cinco horas en la que se reinicia una suscripción. session calcula los totales por conversación, y --instances agrupa por proyecto para mostrar qué repositorio es más costoso. 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, incluidas Codex y OpenCode, lo que resulta útil si las compara.

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 incluyen un coste registrado, por lo que 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, 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 se encuentran en esos discos. 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 último trimestre ya no está disponible a menos que lo haya archivado.

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 ello, 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 es la razón por la que un comando de una sola línea jq escrito manualmente sobre el JSONL es peor idea de lo que parece: los analizadores mantenidos siguen los cambios de formato, mientras que su comando informará de una cifra incorrecta con aparente certeza el día que se 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 cobra por token, por lo que 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 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 realiza localmente a partir del número de tokens y de las tarifas estándar publicadas. Esa cifra 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 qué parte del límite del plan ha utilizado y atribuye el uso reciente a skills, subagents, plugins y servidores MCP individuales como porcentaje del total. También marca 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 alternar 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 hay más de un desarrollador, las cifras pasan al nivel de 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 analítica 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 añade una API de analítica. Lo que se muestra depende del método de inicio de sesión de 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 a fecha de agosto 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 y mida los resultados antes de extrapolarlos.

Los paneles no pueden mostrar nada con un nivel de detalle inferior al día y a la persona. Indicarán que Opus fue el modelo más utilizado durante la mayor parte del martes. No indicarán qué prompt, repositorio o trabajo de CI lo causó. 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 una ejecución descontrolada esta tarde. Para detectar una ejecución descontrolada hacen falta límites, no informes. Ese es el tema de mantener controlados los costes de los agentes en un VPS.

Forma 3: su propia pila de OpenTelemetry le indica qué prompt empeoró

Claude Code emite métricas y eventos de OpenTelemetry después de configurar una variable de entorno, y es la única opción que transmite datos de tokens y costes por usuario a un sistema que usted controla 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: qué parte de la factura corresponde a los subagentes en lugar de a sus propios turnos, si un servidor MCP duplicó los tokens de entrada y si las lecturas de caché se redujeron después de que alguien editara CLAUDE.md. El comportamiento de la caché suele ser la causa de la sorpresa, y cuándo la caché de prompts resulta rentable explica lo que está observando.

Conviene hacer una corrección, porque aparece en todos los hilos 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 trazado 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 proporciona ningún error útil. Langfuse es la herramienta adecuada para los agentes que usted desarrolla directamente mediante la API, donde su propio código crea cada span con su prompt, modelo y coste. Para la CLI de Claude Code, lo adecuado es un almacén de métricas.

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

Bastan dos servicios: un recopilador 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 recopilador es accesible desde sus máquinas y desde ningún otro lugar. La dirección situada delante del puerto es importante, 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 túnel se describe 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 recopilador 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 recopilador debe terminar con Everything is ready. Begin running and processing data.. Si el registro se detiene debido a un error de configuración, significa que el YAML no se pudo analizar y el contenedor se reiniciará en bucle.

Ahora configure Claude Code para usarlo. 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 una petición, 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 reemplaza los puntos por guiones bajos y añade la unidad, por lo que las cadenas exactas dependen de la versión del recopilador. 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 un error claro. Ejecute claude --debug para que el registro de depuración informe de 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á directamente un endpoint de scrape en http://localhost:9464/metrics. Cuando prometheus sea el único exportador indicado, Claude Code omitirá las unidades USD, tokens y s de los nombres de las métricas para que el scrape mantenga un formato de texto válido para Prometheus.

Este diseño implica una decisión de privacidad. De forma predeterminada, sólo salen de la máquina los recuentos; no se envía el texto de las peticiones 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 almacena código fuente y cualquier otro contenido incluido en el contexto. Active estas opciones de forma deliberada 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 sorprenden, porque nadie supervisa 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 tanto, 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 recopilador anterior. Este es el método útil más económico para realizar el seguimiento del gasto 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 hay filas, pero se detienen aproximadamente hace un mes, es cleanupPeriodDays funcionando según lo previsto: las transcripciones se eliminan después de 30 días de forma predeterminada.

Dos equipos muestran totales diferentes. Es normal 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 los descuentos contractuales. 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. Compruebe 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 caché. Cuando caduca, se aplica la tarifa completa de entrada. Por tanto, una pausa larga vuelve a procesar toda la conversación. Esto aparece como un número de entrada grande junto a un número de salida pequeño. los precios de tokens de entrada y salida explica por qué ambos varían de forma independiente.

Un día con subagentes parece imposible. Cada subagente ejecuta su propia ventana de contexto. Por eso, el uso de tokens aumenta según cuántos se hayan ejecutado y cuánto haya durado 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 dejará intentar determinar la causa.

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 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 medida relativa útil para saber qué tan intensa fue una jornada y para 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, un uso de herramienta o una 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 en lugar de usar 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 los 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 desarrolle 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 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 aplican las tarifas estándar de lista. Console informa de lo que realmente se cobró a su organización, en todos los equipos y con todas las claves, después de aplicar los descuentos. 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 puedo realizar el seguimiento del 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 y obtendrá el gasto por canalización sin usar ningún agente, panel ni servicio adicional.