Tracker della spesa di Claude Code a confronto

Cosa legge realmente un tracker della spesa di Claude Code

Ogni tracker della spesa di Claude Code legge una delle tre origini dati, e l'origine determina a quale domanda può rispondere. Un parser dei log legge i file delle trascrizioni delle sessioni presenti sul disco locale. Una dashboard legge i dati di utilizzo che Anthropic conserva per il tuo account o la tua organizzazione. Un backend per le metriche legge il flusso OpenTelemetry (OTel) emesso da Claude Code quando lo abiliti. Tutti e tre possono essere corretti nello stesso momento e fornire comunque risultati diversi, perché contano elementi diversi.

Questa guida non rispiega i token. come Claude Code conteggia l'utilizzo dei token illustra i token di input e output, le scritture nella cache e le letture dalla cache; nessuna dashboard è davvero utile finché questo aspetto non è chiaro. Qui la domanda è più circoscritta: per ogni tipo di strumento, che cosa può vedere e che cosa non potrà mai vedere.

Perché in un solo giorno sono comparsi tre strumenti per monitorare la spesa di Claude Code

Nello stesso giorno sono stati pubblicati tre strumenti distinti per monitorare la spesa di Claude Code. Non erano tre versioni dello stesso strumento, ed è proprio questo l’aspetto utile. Uno analizzava i file delle sessioni locali. Uno integrava le schermate di utilizzo dell’account. Il terzo era un backend di tracing self-hosted da eseguire autonomamente.

Sono comparsi insieme perché il costo di una sessione dell’agente non era più immediatamente evidente. Una chat costa più o meno quanto si vede sullo schermo. Un agente legge venti file, esegue la suite di test e reinvia l’intera conversazione a ogni turno. Di conseguenza, la fattura dipende dal contesto che non hai mai digitato. Con un abbonamento, la cifra in dollari della sessione mostrata da Claude Code è una stima che Anthropic dichiara non rilevante ai fini della fatturazione. Il dato importante è invece una barra di utilizzo che in alcuni giorni si esaurisce più rapidamente che in altri. Ciascuno dei tre strumenti copre una parte diversa di questo divario.

Forma 1: un parser locale dei log mostra quanto è costata la giornata

Claude Code salva ogni conversazione come JSON Lines (JSONL) in ~/.claude/projects/<project>/<session-id>.jsonl, dove <project> è il percorso della directory di lavoro, con i caratteri non alfanumerici sostituiti da -. Ogni turno dell'assistente in quel file contiene il conteggio dei token della richiesta. Un parser dei log li somma e calcola il costo.

ccusage è lo strumento che la maggior parte delle persone sceglie. Non richiede installazione:

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

daily calcola i totali per data. --breakdown suddivide ogni riga per modello, mostrando così che un pomeriggio con Opus può rappresentare gran parte del consumo della settimana. blocks raggruppa i dati in base alla finestra di cinque ore su cui si basa il reset dell'abbonamento. session calcola i totali per conversazione, mentre daily --instances raggruppa i dati per progetto, così puoi vedere quale repository è più costoso. Aggiungi --since e --until per delimitare l'intervallo, quindi usa npx ccusage@latest daily --help per il formato della data previsto dalla tua versione. A ottobre 2026 legge anche i dati di altre CLI per agenti, tra cui Codex e OpenCode. Questo è utile quando vuoi confrontarle.

I prezzi provengono da una tabella dei prezzi dei modelli e lo strumento dispone di tre modalità di calcolo dei costi. --mode auto usa il valore costUSD scritto da Claude Code nel file, quando disponibile, e calcola il costo dai conteggi dei token quando non lo è. --mode calculate calcola sempre il costo dai token e ignora qualsiasi costo registrato. --mode display mostra soltanto i costi registrati e stampa $0.00 per le righe che ne sono prive. Se un totale sembra errato, esegui lo stesso report con calculate e poi con display. Una differenza elevata indica che la maggior parte delle voci non contiene un costo registrato, quindi tutti i valori visualizzati sono stime. Se paghi tariffe contrattuali, pricingOverrides sotto defaults in un file di configurazione ccusage.json sostituisce il prezzo dei singoli modelli.

Gli stessi dati possono alimentare il prompt. ccusage statusline stampa una riga compatta per la barra di stato di Claude Code, configurata in ~/.claude/settings.json come qualsiasi altro comando della barra di stato. Vedi creazione di una barra di stato per Claude Code per il blocco delle impostazioni e i campi che riceve.

Un parser dei log non può vedere ciò che non è avvenuto su questa macchina. Un secondo laptop, una sessione su claude.ai o il lavoro di un collega: quelle trascrizioni risiedono su altri dischi. Anche i dati meno recenti possono mancare, perché per impostazione predefinita le trascrizioni vengono eliminate dopo 30 giorni in base all'impostazione cleanupPeriodDays. I dati dell'ultimo trimestre sono quindi persi, a meno che tu non li abbia archiviati.

Esiste anche un altro rischio, di natura strutturale. La documentazione di Anthropic specifica che il formato delle voci è interno a Claude Code e cambia tra le versioni. Gli script che analizzano direttamente questi file possono quindi smettere di funzionare con qualsiasi release. Questo vale per tutti gli strumenti di questo tipo. È anche il motivo per cui un one-liner jq scritto manualmente per analizzare il JSONL è un'idea peggiore di quanto sembri: i parser mantenuti tengono traccia delle modifiche al formato, mentre il tuo one-liner restituirà un numero errato con apparente certezza il giorno in cui un campo verrà rinominato.

Infine, l'importo in dollari richiede una precisazione per gli abbonamenti. L'utilizzo incluso nel limite del piano Pro o Max non viene fatturato per token. Il valore indica quindi quanto sarebbe costato il consumo applicando le tariffe API pubbliche. Misura l'intensità del tuo utilizzo. Non corrisponde alla fattura. L'eccezione riguarda i crediti di utilizzo: se li abiliti, il consumo oltre il limite del piano viene fatturato alle tariffe API standard come addebito separato, e claude.ai mostra la spesa del mese in Settings > Usage. Se la domanda è quale piano scegliere, il confronto è un'attività distinta: vedi fatturazione API e abbonamento Claude.

Forma 2: le schermate di utilizzo integrate indicano quale modello ha consumato il budget

Claude Code include funzioni di reportistica che la maggior parte degli utenti non apre mai. Esegui /usage durante una sessione. Il riquadro Session nella parte superiore mostra i token per modello e un importo in dollari per la sessione corrente. Il valore viene calcolato localmente in base al numero di token e alle tariffe standard pubblicate, a meno che un amministratore non abbia impostato una tabella modelPricing nelle impostazioni gestite. In tal caso, la riga Total cost indica at your organization's configured rates. In ogni caso, l'importo è una stima e può differire da quello della fattura. Nei piani Pro o Max Anthropic indica che il valore non è rilevante ai fini della fatturazione, perché l'utilizzo è incluso nel piano. I totali vengono azzerati quando /clear avvia una nuova conversazione.

Nei piani Pro, Max, Team o Enterprise basati su postazioni, la stessa schermata mostra la quota utilizzata del limite previsto dal piano. Enterprise basato sul consumo non prevede una quota inclusa da esaurire, perché ogni token viene fatturato alle tariffe API. In questi piani la schermata attribuisce inoltre l'utilizzo recente a skill, subagent, plugin e singoli server MCP, indicandone la percentuale sul totale. Segnala i comportamenti che rappresentano almeno il 10% dell'utilizzo recente, ad esempio contesti lunghi o cache miss. Premi d o w per alternare la visualizzazione delle ultime 24 ore e degli ultimi 7 giorni. Questi valori sono approssimativi e vengono calcolati dalla cronologia delle sessioni memorizzata localmente su questo computer, quindi l'utilizzo di un secondo dispositivo non viene conteggiato. Quando la barra è vuota, anziché semplicemente quasi esaurita, la schermata indica che la finestra è terminata, ma non spiega come continuare a lavorare. Cosa fare dopo aver raggiunto il limite richiede una decisione separata sul modello, sul contesto e sul piano.

Quando gli sviluppatori sono più di uno, i dati vengono aggregati a livello di account. Un'organizzazione API dispone della pagina Usage nella Console, di una dashboard Claude Code con la spesa e le righe accettate per membro e di una Claude Code Analytics API che restituisce le stesse metriche giornaliere per utente tramite una chiave amministrativa. I piani Team ed Enterprise includono un report della spesa nella console di amministrazione, con esportazione CSV e aggiornamento giornaliero. Il report copre però la spesa per crediti di utilizzo: l'utilizzo compreso nella quota della postazione non viene misurato in dollari. Enterprise aggiunge un'analytics API. La visualizzazione dipende dalla modalità di accesso usata da ciascuno sviluppatore. Un'organizzazione con modalità miste deve quindi consultare due report e sommarne manualmente i valori.

Per dimensionare il budget, la cifra pubblicata nella documentazione sui costi di Anthropic a ottobre 2026 è una media vicina a $13 per sviluppatore per giorno attivo e da $150 a $250 per sviluppatore al mese; il 90% degli utenti resta sotto $30 per giorno attivo. Considerala un benchmark pubblicato sulla base di implementazioni enterprise, non una previsione per il tuo team. Esegui un progetto pilota con un gruppo di utenti e raccogli dati prima di fare proiezioni.

Le dashboard non possono mostrare dati più dettagliati del giorno e della singola persona. Indicheranno che Opus è stato utilizzato per la maggior parte della giornata di martedì. Non indicheranno quale prompt, repository o job CI lo abbia causato. Inoltre presentano un ritardo, perché i report dell'organizzazione vengono aggiornati giornalmente. Sono quindi strumenti di analisi a posteriori, non strumenti per rilevare nel pomeriggio un agent che sta generando un consumo incontrollato. Per arrestare questo tipo di consumo servono limiti, non report. Questo è l'argomento di come mantenere sotto controllo i costi degli agent su un VPS.

Schema 3: il tuo stack OpenTelemetry ti indica quale prompt ha causato la regressione

Claude Code genera metriche ed eventi OpenTelemetry dopo l'impostazione di una variabile d'ambiente. È l'unica opzione che invia in streaming, quasi in tempo reale, i dati relativi a token e costi per singolo utente a un sistema sotto il tuo controllo. Le metriche includono claude_code.cost.usage in USD, claude_code.token.usage in token, claude_code.session.count e claude_code.active_time.total.

La metrica dei token è quella più interessante per i suoi attributi. Ogni punto dati contiene type, che può essere input, output, cacheRead o cacheCreation, oltre a model e query_source, che può essere main, subagent o auxiliary. Contiene anche agent.name, skill.name, mcp_server.name e mcp_tool.name. I nomi dei server MCP configurati manualmente e dei subagent personalizzati arrivano come custom, a meno che tu non imposti OTEL_LOG_TOOL_DETAILS=1; questa opzione aggiunge anche i comandi Bash e l'input degli strumenti agli eventi degli strumenti. È sufficiente per rispondere a domande a cui nessuna dashboard può arrivare: quale quota della fattura deriva dai subagent anziché dai tuoi turni, se un server MCP ha raddoppiato i token di input, oppure se le letture dalla cache sono crollate dopo la modifica di CLAUDE.md da parte di qualcuno. Il comportamento della cache è spesso la fonte delle sorprese; quando il prompt caching diventa conveniente spiega come interpretare questi dati.

È opportuno correggere un punto, perché ricorre in ogni discussione sull'argomento. Langfuse è un buon backend di tracing self-hosted, e l'esecuzione su un VPS è descritta in eseguire Langfuse in modalità self-hosted per il tracing degli agenti. Il suo endpoint OTLP accetta solo trace. Per impostazione predefinita, Claude Code esporta metriche ed eventi di log, non span. Di conseguenza, se punti OTEL_EXPORTER_OTLP_ENDPOINT a Langfuse, il progetto resta vuoto e non ottieni alcun errore utile da analizzare. L'esportazione degli span è disponibile, ma in versione beta e disabilitata finché non imposti CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 e OTEL_TRACES_EXPORTER. L'integrazione di Langfuse con Claude Code segue un approccio diverso: un hook Stop, oppure un plugin che ne installa uno, legge le trascrizioni delle sessioni dopo ogni risposta e le converte in trace. Di conseguenza, condivide i limiti locali di un parser dei log. Langfuse è lo strumento adatto per gli agenti che sviluppi direttamente tramite API, dove il tuo codice crea ogni span con il prompt, il modello e il costo associati. Per i totali di spesa della CLI di Claude Code, la scelta corretta è un sistema di metriche.

Configura il monitoraggio della spesa di Claude Code sul tuo VPS

Sono sufficienti due servizi: un collector che riceve le metriche e Prometheus che le archivia. Mantienili entrambi fuori da Internet pubblico, perché una porta OTLP aperta accetta scritture da chiunque la individui. Scrivi /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 è l'indirizzo del server all'interno di un tunnel WireGuard. In questo modo il collector è raggiungibile dai tuoi computer e da nessun altro. L'indirizzo davanti alla porta è importante, perché le porte Docker pubblicate non vengono filtrate da ufw: vedi perché le porte Docker pubblicate ignorano ufw. La configurazione del tunnel è descritta in una VPN WireGuard sul tuo 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. La porta 8889 non viene mai pubblicata sull'host, perché Prometheus raggiunge il collector tramite la rete Compose usando il nome del servizio:

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

Il log del collector dovrebbe terminare con Everything is ready. Begin running and processing data.. Se il log si interrompe a causa di un errore di configurazione, il file YAML non è stato analizzato correttamente e il container verrà riavviato in un ciclo continuo.

Ora configura Claude Code per usarlo. Su ogni computer che esegue Claude Code, aggiungi questo contenuto 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"
  }
}

Avvia una sessione, invia un prompt, attendi l'intervallo di esportazione (qui 10 secondi, 60 secondi per impostazione predefinita), quindi chiedi a Prometheus quali dati ha ricevuto:

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

Dovresti ottenere diversi nomi che iniziano con claude_code_. L'exporter sostituisce i punti con caratteri di sottolineatura e aggiunge l'unità, quindi le stringhe esatte dipendono dalla versione del collector. Un risultato vuoto indica che non è arrivato nulla. Verifica che protocollo e porta corrispondano, perché http/protobuf usa la porta 4318 e grpc usa la porta 4317; una configurazione non corrispondente fallisce senza messaggi evidenti. Esegui claude --debug-file /tmp/claude-debug.log e cerca nel file le righe [3P telemetry], che indicano gli errori di esportazione OTel segnalati da Claude Code.

Per un solo computer e senza server, salta tutti i passaggi precedenti. Imposta OTEL_METRICS_EXPORTER=prometheus: Claude Code espone direttamente un endpoint di scraping all'indirizzo http://localhost:9464/metrics. Quando prometheus è l'unico exporter elencato, Claude Code omette le unità USD, tokens e s dalle metriche esportate, così lo scraping mantiene un formato di testo Prometheus valido. I nomi delle metriche non cambiano e un'impostazione che combina più exporter, come otlp,prometheus, mantiene le unità.

Questa configurazione comporta una decisione sulla privacy. Per impostazione predefinita, dal computer escono soltanto conteggi e metadati; non vengono esportati il testo dei prompt né l'output degli strumenti. OTEL_LOG_USER_PROMPTS=1 aggiunge il testo dei prompt agli eventi esportati e OTEL_LOG_TOOL_CONTENT=1 aggiunge l'output degli strumenti agli span di traccia. Di conseguenza, se esporti uno dei due segnali, il sistema di telemetria conserva il codice sorgente e qualsiasi altro contenuto presente nel contesto. Abilita queste opzioni solo deliberatamente e leggi prima come evitare i secret nel contesto dell'agent.

Monitoraggio dei costi per le esecuzioni tramite script e CI

Le esecuzioni non interattive sono quelle che sorprendono di più, perché nessuno controlla lo schermo. claude -p con --output-format json restituisce nel payload del risultato il costo dell'esecuzione:

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

Il payload contiene total_cost_usd e una suddivisione per modello. Un job CI può quindi registrare i propri costi senza usare una dashboard. Come ogni valore locale, è una stima calcolata lato client. Inoltre, un'esecuzione che continua una conversazione con --continue o --resume restituisce il totale dell'intera conversazione, comprese le esecuzioni precedenti. È possibile aggiungere il valore a un file oppure inviarlo come metrica al collector indicato sopra. Questo è il metodo più economico che fornisca un monitoraggio utile dei costi e richiede una chiamata a jq per ogni esecuzione.

Modalità di errore e risultati visualizzati

Il report è vuoto. npx ccusage@latest daily che non stampa alcuna riga indica che non sta leggendo la posizione in cui Claude Code scrive i dati. CLAUDE_CONFIG_DIR modifica tale posizione e il parser deve essere configurato di conseguenza. Se sono presenti righe, ma si fermano a circa un mese prima, cleanupPeriodDays sta funzionando come previsto: per impostazione predefinita, le trascrizioni vengono rimosse dopo 30 giorni.

Due macchine riportano totali diversi. È previsto e non indica un problema. La suddivisione di /usage e qualsiasi parser dei log leggono solo la cronologia delle sessioni locali. L'utilizzo di un altro dispositivo o di claude.ai non è quindi incluso in nessuno dei due risultati.

Il totale locale non corrisponde alla fattura. I valori locali vengono calcolati a partire dal numero di token e dalle tariffe standard di listino, a meno che non vengano configurate tariffe contrattuali: una tabella modelPricing nelle impostazioni gestite per /usage oppure pricingOverrides per ccusage. Con un abbonamento, l'utilizzo incluso nel limite del piano non viene fatturato per token e vengono addebitati solo i crediti di utilizzo. La pagina Usage della Console è la fonte autorevole per la fatturazione API.

Il costo è aumentato anche se hai svolto lo stesso lavoro. Controlla innanzitutto le colonne della cache. Una sessione lunga invia nuovamente l'intera cronologia a ogni turno. Quando la cache è attiva, i dati vengono tariffati alla relativa tariffa cache; quando scade, vengono tariffati alla tariffa completa per gli input. Di conseguenza, una lunga pausa rielabora l'intera conversazione. Questo risulta evidente da un numero elevato di token di input accanto a un numero ridotto di token di output. Il prezzo dei token di input rispetto a quello dei token di output spiega perché i due valori variano indipendentemente.

Una giornata con gli agenti secondari sembra impossibile. Ogni agente secondario usa una propria finestra di contesto. Il consumo di token aumenta quindi in base al numero di agenti eseguiti e alla durata di ciascuno. In un piano, l'attribuzione di /usage mostra come percentuale la quota degli agenti secondari per questa macchina. Per i dettagli di ogni richiesta, i dati OTel li distinguono tramite l'attributo query_source su claude_code.token.usage. Un parser dei log mostrerà il totale, lasciandoti senza dettagli sull'origine del consumo.

FAQ

ccusage mostra quanto mi viene effettivamente addebitato con un piano Max?

No. L'utilizzo entro il limite del piano di abbonamento non viene addebitato per token. Un parser dei log calcola quindi il costo dei token usando le tariffe API standard di listino e mostra quanto sarebbe costato lo stesso lavoro tramite l'API. È una buona misura relativa dell'intensità di una giornata e consente di confrontare progetti o modelli. Per verificare quanto devi pagare, la pagina Usage della Console mostra la fatturazione API, mentre la pagina di fatturazione del piano mostra i costi dell'abbonamento. Se hai attivato i crediti di utilizzo, l'utilizzo oltre il limite viene addebitato alle tariffe API standard e claude.ai mostra tale spesa in Settings > Usage.

Dove archivia Claude Code i file di sessione letti da questi strumenti?

In ~/.claude/projects/<project>/<session-id>.jsonl, dove <project> è il percorso della directory di lavoro con i caratteri non alfanumerici sostituiti da -. Ogni riga è un oggetto JSON relativo a un messaggio, all'utilizzo di uno strumento o a una voce di metadati. CLAUDE_CONFIG_DIR sposta l'intera directory, mentre cleanupPeriodDays in settings.json controlla la conservazione per 30 giorni. Anthropic documenta il formato delle voci come interno e soggetto a modifiche tra le versioni. Usa quindi uno strumento mantenuto, invece di uno script proprietario.

Posso inviare la telemetria di Claude Code a Langfuse?

Non con la telemetria predefinita. L'endpoint OTLP di Langfuse accetta le trace. Per impostazione predefinita, però, Claude Code esporta metriche ed eventi di log invece degli span, quindi i dati non hanno una destinazione compatibile. L'esportazione degli span è una funzione beta che devi attivare. L'integrazione proprietaria di Langfuse per Claude Code usa invece un hook Stop che converte i transcript delle sessioni in trace. Per i totali di spesa, invia le metriche di Claude Code a un collector OpenTelemetry e archiviali in Prometheus. Usa Langfuse per gli agenti che sviluppi direttamente sull'API, dove il tuo codice genera span contenenti prompt, modello e costo.

Perché i valori locali non corrispondono alla pagina Usage della Console?

Perché vengono calcolati in modo diverso. /usage e i parser dei log sommano i conteggi dei token dai file di sessione presenti sul computer in uso, quindi applicano le tariffe standard di listino, salvo configurazione di tariffe contrattuali, tramite modelPricing nelle impostazioni gestite per /usage oppure pricingOverrides per ccusage. La Console mostra quanto è stato effettivamente addebitato alla tua organizzazione, considerando tutti i computer e tutte le chiavi, dopo l'applicazione degli eventuali sconti. Una differenza è normale. Una differenza molto grande indica in genere un secondo dispositivo, un runner CI o un altro membro del team che addebita i costi allo stesso account.

Come posso monitorare il costo di un'esecuzione claude -p in CI?

Eseguila con --output-format json e leggi total_cost_usd dal risultato, ad esempio con claude -p "..." --output-format json | jq '.total_cost_usd'. Lo stesso payload include una suddivisione per modello e l'ID della sessione. Registra quel valore per ogni job e otterrai la spesa per pipeline senza agenti, dashboard o servizi aggiuntivi.