Capire il consumo di token
in Claude Code

Primi passi#

Installare. In Obsidian: Impostazioni → Plugin della community → Sfoglia → cerca «Token Usage» → Installa → Attiva. È tutta la configurazione: nessun account da creare, nessuna chiave API da incollare, nessun servizio esterno. Funziona allo stesso modo su Windows, macOS e Linux; l'unico dettaglio specifico di una piattaforma (dove la modalità agente dell'app desktop di Claude salva le sue sessioni) è spiegato in Fonti dei dati e trasparenza.

Aprirlo. Fai clic sull'icona del grafico nella barra multifunzione a sinistra, oppure esegui «Open Token Usage» dalla palette dei comandi (Ctrl/Cmd+P). Entrambi aprono la vista nella barra laterale destra, dove resta come qualsiasi altro pannello di Obsidian.

Niente da configurare per avere numeri utili. La barra laterale funziona subito: a sinistra una barra di icone con quattro pagine, Panoramica, Calendario, Analisi e Impostazioni, vedi più sotto. Dalla 2.0 esiste solo questo layout; la vecchia vista «Classic» e l'impostazione per passare dall'una all'altra non ci sono più.

Comandi disponibili dal primo giorno (palette dei comandi, i nomi dei comandi sono in inglese):

Fonti dei dati e trasparenza#

Questo plugin ha bisogno di accesso diretto al file system per funzionare. La revisione dei plugin della community di Obsidian lo segnala come un avviso previsto, non come un difetto, perché leggere i file di sessione locali è proprio il suo scopo. Invece di chiederti una fiducia cieca, ecco esattamente dove si trovano questi file, quali campi legge il plugin e cosa non tocca mai. Ogni affermazione si può verificare nel codice sorgente: main.js non è minificato ed è pubblico su GitHub.

Dove si trovano davvero i file JSONL. Claude Code, che giri in un terminale, in un editor come VS Code o dentro Obsidian, scrive un file JSONL per sessione in ~/.claude/projects/<workspace-id>/<session-id>.jsonl, una sottocartella per ogni directory di lavoro. È identico su Windows (C:\Users\<tu>\.claude\projects\...), macOS (/Users/<tu>/.claude/projects/...) e Linux (/home/<tu>/.claude/projects/...); il plugin la trova con os.homedir() di Node, che funziona allo stesso modo ovunque. Interviene un altro file, solo in lettura finché non usi l'impostazione di conservazione del plugin: il ~/.claude/settings.json di Claude Code, da cui viene letto solo il valore cleanupPeriodDays. Se lo modifichi dalle impostazioni del plugin, prima viene scritta automaticamente una copia .bak dell'intero file. E solo se configuri il feed facoltativo: ~/.claude/ratelimit-log.jsonl, solo in lettura, le percentuali ufficiali con i loro orari di reset.

Modalità agente di Claude Desktop: un'eccezione solo di Windows, per quanto se ne sa oggi. La versione Windows dell'app desktop di Claude esegue il suo Claude Code integrato in una sandbox di contenitore d'app MSIX, che virtualizza il file system. Per questo le sessioni della modalità agente finiscono lì in un altro posto: %APPDATA%\Claude\local-agent-mode-sessions\... oppure, nella versione del Microsoft Store, nel percorso isolato %LOCALAPPDATA%\Packages\<package-id>\LocalCache\Roaming\Claude\local-agent-mode-sessions\.... Il plugin esamina automaticamente questa seconda posizione dalla v1.8.0, solo su Windows. macOS e Linux non hanno uno strato di sandbox equivalente e, secondo la documentazione disponibile, Claude Code scrive lì nella stessa ~/.claude/projects/, che si tratti della riga di comando, delle integrazioni con gli editor o dell'app desktop. Su macOS e Linux le sessioni della modalità agente (dove esiste) dovrebbero quindi arrivare già nella posizione standard che il plugin legge. È la migliore evidenza attuale, non una fonte primaria di Anthropic: se usi la modalità agente su macOS o Linux e manca del consumo, apri una issue su GitHub.

L'unica cosa che non è un numero. Claude Code scrive da sé un breve titolo generato automaticamente per ogni sessione nello stesso file JSONL (una voce ai-title). La tabella Top Sessions della dashboard legge quell'unica breve stringa e la mostra al posto di un identificativo di sessione grezzo, solo perché l'elenco sia leggibile. È l'unico campo che deriva dal contenuto della conversazione e non da numeri di utilizzo, ed è il riassunto di Claude Code stesso, nulla che il plugin generi o ampli.

Cosa lascia il tuo computer: niente. Nessuna richiesta di rete, nessuna telemetria, nessun server esterno: ogni numero viene calcolato in locale. Il plugin scrive esattamente due tipi di file nuovi, entrambi nel tuo vault ed entrambi solo con totali: l'archivio giornaliero in Token Usage Archive/ (vedi Archivio e dati a lungo termine) e, solo quando li richiedi tu, il report in Markdown, la dashboard HTML, l'esportazione per vault e progetto e le esportazioni CSV. Nessuno contiene mai un prompt o una risposta.

Se vuoi controllare il browser da solo. Gli strumenti per sviluppatori del browser (F12 → scheda Rete, filtrata su XHR/Fetch) mostrano ogni richiesta mentre usi claude.ai. Due avvertenze oneste: questo plugin non fa nulla di tutto ciò per te, non ha integrazione con il browser, né estensione, né proxy, ed è un limite voluto. E il client web di claude.ai parla con endpoint interni e non documentati di Anthropic, non con l'API pubblica di Claude usata da Claude Code: i numeri simili a token che vedi lì sono dettagli interni che possono cambiare senza preavviso. L'oggetto usage dell'API pubblica, quello che Claude Code scrive nei tuoi file JSONL locali e che questo plugin legge, resta l'unica fonte stabile e documentata dei conteggi esatti dei token.

Limiti: percentuali solo da Anthropic#

Le percentuali ora arrivano solo da Anthropic. Fino alla 2.1, Token Usage stimava una percentuale per la finestra di 5 ore e per la settimana, dai tuoi limiti raggiunti o proiettata dal feed. Abbiamo confrontato questa stima con i valori ufficiali per undici giorni. Per la finestra di 5 ore si discostava in media di 36 punti, e nel momento in cui una finestra era ufficialmente piena il nostro anello segnava un valore qualsiasi tra il 61 e il 217 per cento (nostra misurazione, 37 letture, dal 6 al 17 ottobre 2026). La velocità con cui una finestra si riempie dipende molto da quanto contesto una sessione si porta dietro, e i log locali non possono dirlo in modo affidabile. Gli anelli suggerivano una precisione che non hanno mai avuto. È stata una nostra decisione, ed era sbagliata.

Dalla 2.5 vale una regola semplice: mostriamo una percentuale per un limite solo se arriva da Anthropic, insieme all'ora in cui è stata letta. Per questo ti serve il feed (vedi Percentuali ufficiali di Anthropic). Facciamo un'eccezione per la settimana: tra due letture proiettiamo l'ultimo valore ufficiale con i tuoi token contati e lo indichiamo come tale, perché il limite settimanale si è rivelato stabile nella stessa misurazione (1,2 punti di scarto medio). Senza il feed vedi ciò che sappiamo con certezza: i tuoi token nella finestra attuale e nella settimana, il tempo fino al reset e l'intervallo in cui la tua finestra di 5 ore si è riempita finora. L'anello Oggi non mostra più una percentuale, ma un multiplo della tua giornata tipica. Tutto il resto del plugin viene contato e resta com'è.

Perché i token sotto un anello non corrispondono alla sua percentuale. Il plugin conta input e output. Anthropic conta anche il contesto che una sessione invia con ogni richiesta, quindi percentuale e token non coincidono direttamente. Una sessione lunga che si porta dietro un contesto grande può riempire una finestra con relativamente pochi token contati. Quello che conta è la percentuale.

Cosa resta: l'intervallo dei tuoi limiti raggiunti. Sotto gli anelli il plugin indica il numero di token più basso e quello più alto con cui la tua finestra di 5 ore si è riempita finora, per esempio «Finora la tua finestra di 5h era piena dopo un valore tra 51 K e 316 K (102 limiti raggiunti)». Conta input e output dall'inizio della finestra fino a ogni limite raggiunto. Non è un limite né una previsione: mostra quanto è davvero ampio l'intervallo. Con il feed l'inizio della finestra arriva da Anthropic. Senza, viene ricostruito dai tuoi log e può differire di qualche minuto se claude.ai o un altro dispositivo ha aperto la finestra. Senza il feed, una breve riga sotto gli anelli porta direttamente alla configurazione.

Fino alla 2.1 sulle altre pagine questa sezione si chiamava «Rate limit stimati» e prometteva che la stima sarebbe diventata più precisa a ogni limite raggiunto. La misurazione sopra ha mostrato che non era così.

Che cos'è un token?#

Un token è un piccolo pezzo di testo, circa tre quarti di una parola inglese; in italiano le parole si dividono spesso in un po' più di token. Non è esattamente una parola né esattamente un carattere. La frase «Buongiorno, come stai oggi?» dà circa 8 token. Le parole lunghe o insolite costano di più; quelle brevi e frequenti a volte condividono un token. Il tuo input e la risposta di Claude vengono contati separatamente.

Input e output#

L'input è tutto ciò che Claude riceve in una richiesta: il tuo messaggio, il prompt di sistema, il contenuto dei file, i risultati degli strumenti e la cronologia della conversazione, rinviata a ogni nuovo turno.

L'output è ciò che Claude scrive in risposta. I token di output costano sempre più di quelli di input, in tutti i modelli, di solito da 3 a 5 volte tanto.

Una singola domanda costa poco. I costi crescono con il volume, la dimensione del contesto e la ripetizione, non con la complessità di ciò che chiedi.

C.Write — scrittura nella cache#

Quando Claude Code invia un blocco di testo grande e ripetuto (file del progetto, un lungo prompt di sistema, un'intera base di codice), l'infrastruttura di Anthropic può metterlo in cache. La prima volta che quel blocco viene elaborato, viene scritto nella cache. Questa è una scrittura nella cache.

Esistono due tipi di scrittura nella cache, con prezzi diversi: una scrittura nella cache di 5 minuti costa 1,25 volte il prezzo di input standard, una scrittura nella cache di 1 ora costa 2 volte. Nei nostri log, circa il 90 % delle scritture nella cache di Claude Code con abbonamento era del tipo da 1 ora, mentre i subagenti scrivevano cache da 5 minuti. Dalla 2.1.0, passando il mouse su una riga C.Write nella barra laterale vedi la ripartizione per quel periodo. È un investimento: paghi di più all'inizio perché le richieste successive non debbano rielaborare lo stesso contenuto. Le scritture nella cache contano anche per il limite di 5 ore, vedi Cosa conta per un limite.

Il plugin mostra C.Write in acquamarina in tutta la barra laterale.

C.Read — lettura dalla cache#

Una volta che un blocco è in cache, Claude può leggerlo dalla cache nelle richieste successive invece di elaborarlo da zero. Questa è una lettura dalla cache.

Le letture dalla cache costano solo una frazione del prezzo di input standard: 0,1 volte nella maggior parte dei modelli, 0,05 volte su Opus 5.5 e Sonnet 5.5, 0,025 volte su Fable 5.1. Se lo stesso contesto viene usato molte volte, le letture dalla cache rendono le sessioni grandi molto più economiche di quanto sarebbero altrimenti.

Il plugin mostra C.Read in viola per indicare molto volume a basso costo per token.

C.Write vs C.Read — il fattore di riutilizzo e cosa dice del tuo modo di lavorare#

Il rapporto tra questi due numeri è più di un dettaglio di costo: è una lettura diretta e onesta di quanto un periodo di lavoro sia stato concentrato o dispersivo.

Un riutilizzo alto significa che sei rimasto sullo stesso contesto con domande di approfondimento invece di ricominciare continuamente; uno basso significa cambi di contesto quasi continui. Nessuno dei due è «sbagliato», l'esplorazione ha il suo posto, ma se volevi un lavoro profondo e prolungato e il fattore dice altro, vale la pena notarlo. La dashboard mostra questo rapporto nella sezione sull'efficienza della cache, con un grafico a linee con C.Write in acquamarina e C.Read in viola, come nella barra laterale.

Focus Score, un secondo segnale indipendente. Il Focus Score della dashboard (da 0 a 100) combina tre cose che il plugin vede già: il riutilizzo della cache (le fasce sopra, il 50 % del punteggio), la continuità (poche sessioni lunghe per giorno attivo valgono più di molte brevi, 30 %) e la profondità (più scambi per sessione valgono più delle domande isolate, 20 %). Il risultato dà un badge: Deep Work Mode (da 80), Focused (da 60), Balanced (da 40) o Scattered (sotto 40).

Per chi inizia: l'abitudine più efficace è restare in una sessione continua per un problema continuo e fare domande di approfondimento invece di rispiegare il contesto in un nuovo messaggio. Di solito alza entrambi i numeri ed è comunque un modo migliore di lavorare. Per chi ha esperienza: un fattore costantemente basso su un intero progetto può indicare che il prompt di sistema o il contesto condiviso viene ricostruito ogni volta invece di essere riutilizzato. Conviene correggerlo nel flusso di lavoro (sessioni più lunghe, un file di riferimento condiviso, subagenti che ereditano il contesto) invece di accettarlo come un costo normale.

Finestra di 5 ore corrente#

Claude Code applica una finestra di 5 ore, ed è ancorata, non mobile. La finestra si apre con il tuo primo messaggio e dura esattamente cinque ore; una nuova inizia solo quando quel periodo è trascorso del tutto, concatenata in blocchi fissi di cinque ore, indipendentemente da quanto tempo di inattività ci sia in mezzo. Non sono «le ultime cinque ore contate all'indietro da adesso», ed è indipendente dal reset settimanale, che segue un proprio calendario e non avvia una nuova finestra di 5 ore.

Il plugin ricostruisce queste finestre reali dalla tua attività e somma quella aperta, con input, output, C.Write e C.Read su righe separate. Questo conta proprio nel momento in cui una finestra cambia: un calcolo mobile sommerebbe la coda della finestra appena chiusa alla testa di quella appena aperta, e darebbe un numero che non appartiene a nessuna delle due, proprio quando vuoi vedere che hai un budget nuovo.

È la vista più immediata del tuo lavoro in corso. Se lavori da un po' senza una pausa lunga, questa finestra mostra ciò che hai consumato da quando si è aperta.

Perché il conto alla rovescia mostra una tilde (~)

Il conto alla rovescia del reset, in fondo alla barra laterale, dice «Claude 5h resets in: ~Xh Ym». La tilde è voluta: indica un'approssimazione, non un valore esatto.

Claude Code scrive i dati di sessione nei file locali dopo che ogni risposta è completata, non nel momento in cui invii il primo messaggio. All'inizio di una sessione la prima richiesta è spesso lunga: caricare il contesto, leggere file, ragionare. Questa prima risposta può richiedere da 10 a 25 minuti, e nel frattempo nel log locale non viene ancora scritto nulla. Il primo timestamp che il plugin può leggere non è quindi l'inizio reale della tua sessione, ma il momento in cui è arrivata la tua prima risposta.

Per questo il conto alla rovescia del plugin può essere in ritardo di 10-25 minuti rispetto a quello di Claude. Per l'ora esatta, controlla la sezione sull'utilizzo del piano in Claude Code o su claude.ai. Il valore del plugin è un orientamento affidabile, ma quello che mostra Claude è la fonte di riferimento.

Con il feed (vedi Percentuali ufficiali di Anthropic) questa differenza sparisce: ogni lettura contiene il momento in cui la finestra attuale si azzera. Appena esiste una lettura della finestra attuale, il plugin usa l'inizio ufficiale, anche se la finestra è stata aperta su claude.ai, su un altro dispositivo o in un altro strumento.

Le tre viste temporali e come si relazionano#

La barra laterale mostra tre riepiloghi diversi della tua attività: Finestra di 5 ore corrente, Questa sessione e Oggi. Sono tre viste indipendenti sugli stessi dati: non si annidano automaticamente l'una nell'altra come farebbero ore, giorni e settimane.

La conseguenza principale: una sessione può durare più giorni. Se ieri hai iniziato una sessione lunga e oggi l'hai continuata, «Questa sessione» mostra più token di «Oggi». È previsto: la sessione si accumula oltre il cambio di data, mentre «Oggi» conta solo dalla mezzanotte.

Allo stesso modo, la finestra di 5 ore non è una parte di «Oggi»: una finestra aperta ieri sera tardi va oltre la mezzanotte, e tutto ciò che contiene conta sempre per lo stesso limite. Le due possono anche coincidere: se la tua finestra si è aperta stamattina e prima oggi non avevi lavorato, entrambi i numeri sono uguali finché la finestra non si chiude.

Il plugin lo rende visibile: una piccola riga sotto il titolo di ogni sezione ne indica l'ambito. «Questa sessione» mostra quando è iniziata la sessione, così vedi subito se i numeri coprono più giorni.

Modelli#

Claude Code invia le richieste a modelli diversi a seconda del compito. La barra laterale mostra una barra percentuale impilata con la distribuzione dei modelli negli ultimi 7 giorni, ogni famiglia nel proprio colore:

I colori dei modelli evitano di proposito il verde, l'ambra e il rosso. In questo plugin quei tre significano bene, attenzione e critico: un colore identifica qualcosa o lo giudica, mai entrambe le cose. Fino a ottobre 2026 le pagine di aiuto nelle altre lingue indicavano ancora i colori precedenti alla 2.0 (ciano, blu, viola, ambra).

Conoscere il tuo mix di modelli spiega gran parte della variazione dei costi da un giorno all'altro. Una giornata con molto Opus costa tutt'altro che una passata soprattutto con Haiku. Per la gamma attuale e i prezzi esatti, fa fede la pagina dei prezzi di Anthropic, vedi anche Prezzi dell'API più sotto.

Sessioni#

Claude Code scrive un file di log JSONL per sessione. Il plugin legge tutti i file in ~/.claude/projects/ e raggruppa il consumo per sessione. La tabella Top Sessions della dashboard mostra quali esecuzioni hanno consumato più token, utile per individuare sessioni inaspettatamente costose.

Cosa conta per un limite#

Anthropic applica due limiti e nient'altro: la finestra di 5 ore sopra e un tetto settimanale che si azzera in un momento fisso. Non esiste un limite giornaliero, quindi l'anello Oggi non è una quota (vedi L'anello Oggi).

Contano i token di input e di output, e anche la cache non è gratuita. Le misurazioni rispetto alle percentuali ufficiali che Claude Code riporta (ottobre 2026) indicano che le scritture nella cache contano chiaramente per la finestra di 5 ore e le letture un po'. Un'analisi precedente dei limiti raggiunti indicava il contrario; le nuove misurazioni sono più dirette. I numeri del plugin contano sempre solo input e output. Quando una sessione lunga deve ricostruire la cache, per esempio in una nuova finestra di 5 ore dopo una pausa o quando un grande contesto viene caricato per la prima volta, il valore ufficiale può quindi andare avanti rispetto al plugin. In pratica: le sessioni lunghe con molto contesto consumano la finestra di 5 ore più in fretta, per risposta, di quelle brevi e nuove.

Anthropic non pubblica nessuno dei due limiti in token. Per questo, dalla 2.5, Token Usage mostra una percentuale per un limite solo se arriva da Anthropic, sempre con l'ora della lettura (vedi Limiti: percentuali solo da Anthropic). Serve il feed, un piccolo file con le percentuali ufficiali (vedi Percentuali ufficiali di Anthropic). Tra due letture la settimana viene proiettata con i tuoi token contati e indicata come «proiettato». La finestra di 5 ore no, perché la velocità con cui si riempie dipende soprattutto da quanto contesto una sessione si porta dietro, e i log locali non possono dirlo in modo affidabile. Senza il feed vedi i token contati, il tempo fino al reset e l'intervallo in cui la tua finestra di 5 ore si è riempita finora.

L'anello Oggi#

Non esiste un limite giornaliero. Anthropic limita solo la finestra di 5 ore e la settimana. L'anello Oggi confronta ciò che hai usato oggi con la tua media per giorno attivo, calcolata su tutti i giorni che Claude Code conserva su disco (la tua impostazione di conservazione dei dati, cleanupPeriodDays).

Dalla 2.5 lo mostra come multiplo, non come percentuale: «2,0x la tua giornata tipica» significa che oggi lavori il doppio del solito, nient'altro. Una giornata intensa è un cambiamento nel modo di lavorare, non un avviso, per questo l'anello resta grigio neutro (dalla 2.1.0). Quanto sei vicino a un limite lo mostrano solo gli anelli della finestra di 5 ore e della settimana, e solo con un valore ufficiale. Fino alla 2.1 lo stesso confronto diceva «200 %»; con il multiplo, ogni percentuale sullo schermo arriva da Anthropic oppure è una proiezione settimanale indicata come tale a partire da un valore di Anthropic.

Percentuali ufficiali di Anthropic (il feed)#

Facoltativo, dalla 2.1.0. Claude Code conosce le percentuali ufficiali del tuo piano, i numeri che mostra /usage. Due piccoli script del repository del plugin le scrivono in ~/.claude/ratelimit-log.jsonl. Dalla 2.5 questo file è l'unica fonte di percentuali dei limiti in Token Usage: senza, gli anelli della finestra di 5 ore e della settimana restano grigi e mostrano i token contati e il tempo fino al reset; tutto il resto funziona allo stesso modo. La guida completa (in inglese) si trova nella cartella extras su GitHub.

Cosa ci guadagni

Un esempio reale dai nostri dati, 27 ottobre 2026: alle 13:10 il plugin proiettava la settimana da un 24 % ufficiale a circa il 28 %; la lettura ufficiale successiva, sei minuti dopo, diceva 29 %.

Requisiti

• Un abbonamento Pro o Max con cui Claude Code ha effettuato l'accesso. Con una chiave API non ci sono percentuali del piano.
• Node.js, perché entrambi gli script sono piccoli programmi Node. Controlla con node --version. Se manca, installa la versione LTS dal sito di Node.js. Claude Code installato con l'installer nativo non include Node.js.
• Una versione recente di Claude Code e, per l'interrogazione pianificata, la riga di comando claude.

Quale script mi serve?

Una riga di stato funziona solo finché il terminale interattivo di Claude Code è aperto. I client che integrano Claude Code non la eseguono, quindi lì la sola riga di stato produce poche letture o nessuna.

Opzione A: script della riga di stato

Copia lo script in ~/.claude/ratelimit-statusline.js e aggiungi questa voce a ~/.claude/settings.json, accanto alle chiavi già presenti:

"statusLine": { "type": "command", "command": "node ~/.claude/ratelimit-statusline.js" }

Su Windows usa il percorso completo con le barre normali, per esempio node C:/Users/<tu>/.claude/ratelimit-statusline.js. Riavvia Claude Code; la riga di stato mostrerà 5h 12% | week 34%. Usi già una tua riga di stato? Tienila e aggiungi la parte di registrazione del nostro script.

Opzione B: interrogazione pianificata

Prima di configurarla: ogni esecuzione è una richiesta reale e minuscola (il prompt ok a Haiku, senza salvare la sessione) e conta per il tuo consumo. Se in quel momento non c'è nessuna finestra di 5 ore aperta, la richiesta ne apre una, e la tua finestra successiva inizia all'ora dell'interrogazione. Pianificala per orari in cui lavori comunque; tre volte al giorno bastano ampiamente per la settimana, che il plugin proietta tra le letture. L'anello di 5 ore mostra solo una lettura della finestra attuale, quindi con tre interrogazioni al giorno è grigio la maggior parte del tempo; è lo stato onesto, non un errore. Dalla 2.5 lo script riprova una volta dopo un timeout: un'esecuzione subito dopo il risveglio dalla sospensione spesso non ha ancora la rete.

Oppure solo mentre lavori (dalla 2.5, consigliato se vuoi vedere l'anello di 5 ore). Avviato con --only-when-active, lo script controlla prima se Claude Code ha scritto nei suoi log di sessione negli ultimi 20 minuti e altrimenti termina senza richiesta. Mentre lavori una finestra di 5 ore è comunque aperta, quindi l'interrogazione non ne apre praticamente mai una da sola e può girare ogni 30 minuti. L'anello di 5 ore mostra allora un valore ufficiale per la maggior parte del tempo in cui lavori. Ogni esecuzione con attività è una richiesta minuscola, quelle senza attività non costano nulla. I comandi di questa variante per Windows, macOS e Linux sono nella guida della cartella extras citata sopra; con cron basta */30 7-23 * * * con l'opzione alla fine.

Copia lo script in ~/.claude/ratelimit-poll.js ed eseguilo una volta a mano con node ~/.claude/ratelimit-poll.js. Stampa 5h 12% | week 34%. Poi pianificalo.

Windows (PowerShell, viene eseguito alle 12:00, 17:00 e 22:00 e recupera le esecuzioni perse se il computer era spento):

$node     = (Get-Command node).Source
$script   = "$env:USERPROFILE\.claude\ratelimit-poll.js"
$action   = New-ScheduledTaskAction -Execute $node -Argument "`"$script`""
$triggers = '12:00','17:00','22:00' | ForEach-Object { New-ScheduledTaskTrigger -Daily -At $_ }
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable
Register-ScheduledTask -TaskName 'TokenUsageLimitPoll' -Action $action -Trigger $triggers -Settings $settings

macOS e Linux (crontab -e, con percorsi completi ottenuti da which node e which claude, perché cron gira con un PATH minimo):

0 12,17,22 * * * CLAUDE_BIN=/percorso/completo/di/claude /percorso/completo/di/node /Users/<tu>/.claude/ratelimit-poll.js

Su Linux la cartella personale di solito è /home/<tu>. Gli errori delle esecuzioni pianificate finiscono in ~/.claude/ratelimit-poll-errors.log. Se lo script non trova la riga di comando di Claude Code, imposta CLAUDE_BIN con il suo percorso completo.

Verificare che funzioni

• Il file ~/.claude/ratelimit-log.jsonl esiste e riceve nuove righe.
• Aggiorna la barra laterale. L'anello settimanale mostra una percentuale con «lettura hh:mm» (oppure «proiettato» con il valore ufficiale sotto), e l'avviso «Le percentuali ufficiali richiedono il feed.» sotto gli anelli è sparito. L'anello di 5 ore mostra una percentuale subito dopo una lettura nella finestra attuale. Nella dashboard i riquadri indicano «official percentage from Anthropic» oppure «projected from the last official value».
• Subito dopo una lettura, /usage in Claude Code e gli anelli del plugin mostrano le stesse percentuali.

Come il plugin usa le letture

• Inizio della finestra: ogni lettura contiene il momento in cui la finestra di 5 ore attuale si azzera. La finestra sono le cinque ore precedenti, così il plugin conosce l'inizio reale anche se la finestra è stata aperta dove lui non può vedere.
• Anello 5 ore: mostra l'ultima lettura solo finché la sua finestra è aperta, con l'ora della lettura e i token contati da allora. Dentro una finestra il valore ufficiale può solo salire, quindi è un minimo. Non viene proiettato nulla. Una lettura di una finestra precedente non viene mostrata.
• Anello settimanale: mostra l'ultima lettura della settimana in corso. Tra due letture viene proiettato con i tuoi token contati rispetto al limite settimanale che risulta dalle letture (token della settimana fino a una lettura divisi per la sua percentuale, dalle letture del 10 % in su; sotto, l'arrotondamento all'intero è troppo grossolano) e indicato come «proiettato». Dopo un reset settimanale senza nuova lettura riparte da 0 % con il limite della settimana precedente, indicato come «proiettato dal reset».
• Crediti di utilizzo: con i crediti di utilizzo (usage credits) puoi continuare a lavorare dopo il limite settimanale. Le letture al 100 % o oltre, e tutto ciò che segue nella stessa settimana, non vengono usate per il limite settimanale; una settimana al 100 % mostra il valore ufficiale senza proiettarlo.
• Reset settimanale: preso dalla lettura come momento esatto, quindi resta corretto anche con il cambio dell'ora.
• Altre finestre: se Anthropic segnala più della finestra di 5 ore e della settimana (per esempio un limite settimanale proprio di un modello), entrambi gli script lo registrano e il plugin lo mostra sotto gli anelli, così come arriva.
• Un periodo senza feed: senza una lettura adatta gli anelli tornano grigi e mostrano i token contati e il tempo fino al reset. Nel frattempo non viene stimato nulla.

Limiti noti

• La proiezione settimanale conta solo input e output. Ufficialmente contano anche le scritture nella cache (le letture un po'). Nell'arco di una settimana questo si compensa bene (1,2 punti di scarto medio nella nostra misurazione), ma una grande ricostruzione della cache si vede del tutto solo con la lettura successiva.
• Le letture esistono solo quando uno script è in esecuzione: finché è visibile una riga di stato oppure agli orari pianificati.
• Percentuali intere: i valori ufficiali arrivano arrotondati. Un punto percentuale di una finestra di 5 ore può valere qualche migliaio di token.

Risoluzione dei problemi

Privacy e rimozione

Tutto resta sul tuo computer. Ogni riga contiene un timestamp, le percentuali con i loro orari di reset e, dalla riga di stato, l'identificativo di sessione e di modello. Il plugin legge soltanto il file e non esegue mai gli script da sé. Per rimuoverlo, elimina la voce statusLine, l'attività pianificata (Unregister-ScheduledTask -TaskName 'TokenUsageLimitPoll') o la riga di cron e, se vuoi, il file di log. Gli anelli della finestra di 5 ore e della settimana restano allora grigi e mostrano i token contati e il tempo fino al reset.

Reset settimanale#

Il limite settimanale si azzera in un momento fisso, diverso per ogni account. Tutto ciò che riguarda la settimana dipende da questo: l'anello settimanale, la previsione e la mappa di attività.

Di solito non devi impostare nulla. Con il feed il plugin prende il reset esatto dalla lettura ufficiale. Senza, lo legge dal messaggio che Claude scrive quando raggiungi un limite settimanale. In entrambi i casi le impostazioni mostrano un segno di spunta verde e da dove arriva il valore. Finché non è stato rilevato alcun reset, il plugin presume domenica alle 18:00 e lo dice.

Cambio dell'ora. Il reset di Anthropic è fissato in UTC, quindi il suo orario locale si sposta di un'ora quando cambia l'ora. Fino alla 2.1 il plugin lo salvava come giorno e ora locali, per cui dopo il passaggio all'ora solare ogni confine di settimana era spostato di un'ora. Dalla 2.5 un reset rilevato viene conservato come momento esatto e segue il cambio da solo.

Puoi impostarlo a mano in Impostazioni → Reset settimanale. Un'impostazione manuale prevale e resta in ora locale: il rilevamento automatico non la sovrascrive, la conferma soltanto.

La barra laterale, la mappa di attività e il calendario#

Una barra di icone a sinistra passa da una pagina all'altra, quattro in tutto. Dalla 2.0 è l'unico layout; la vecchia vista «Classic» e l'impostazione per passare dall'una all'altra sono state rimosse.

Tutto ciò che c'è in Panoramica riguarda di proposito oggi o la settimana in corso; ciò che copre un periodo più lungo sta in Analisi o nella dashboard. Nell'intestazione, Dashboard e Report generano file, CSV esporta nel tuo vault e la freccia forza un aggiornamento immediato.

Ciascuna delle quattro righe di token della Panoramica ha un piccolo indicatore: un punto verde quando il valore è vicino alla tua media recente, una freccia ambra quando è nettamente sopra. Il periodo di confronto segue la tua impostazione di conservazione dei dati Claude, non un numero fisso di giorni.

Mappa di attività

La griglia della Panoramica copre la settimana di fatturazione in corso. Una riga per giorno di calendario, una cella ogni due ore, dodici celle al giorno.

Ha otto righe, non sette: una settimana che va, per esempio, da domenica alle 17:00 alla domenica successiva alle 17:00 tocca otto date, quindi la prima e l'ultima riga sono di proposito parziali. Le celle fuori dalla finestra sono disegnate solo come contorni vuoti; è questo che rende visibile il confine del tuo ciclo invece di nasconderlo in fette artificiali di 24 ore.

Il colore confronta ogni cella con il tuo blocco tipico di 2 ore: la media di tutti i blocchi di 2 ore con attività nei giorni conservati (il valore è indicato sotto la griglia). Basso è sotto la metà, medio fino a quel valore, alto fino al doppio, rosso oltre il doppio. La sfumatura all'interno di una fascia mostra dove si colloca una cella. Fino alla 2.1 le celle venivano misurate rispetto a un limite di 5 ore stimato, che non esiste più.

Si distinguono tre tipi di niente: fuori dalla finestra (solo contorno), non ancora raggiunto (tenue) e davvero nessuna attività (pieno). Solo l'ultimo dice qualcosa su com'è andata la tua settimana. Accanto alla griglia, Giorni attivi conta i giorni di questa settimana di fatturazione con almeno un'attività.

Calendario attività

La pagina Calendario mostra gli ultimi due mesi uno accanto all'altro. Due invece di uno, perché all'inizio del mese una sola griglia mostrerebbe solo pochi giorni utili e nasconderebbe proprio il periodo precedente che stai cercando. Le frecce spostano la coppia più indietro, fin dove arriva l'archivio; il calendario non va mai nel futuro.

Ogni giorno passato ha un punto colorato misurato rispetto alla tua media giornaliera recente: verde sotto, ambra intorno, rosso per un picco (2x o più). I giorni senza attività non hanno il punto. Fai clic su un giorno per aggiungere una nota privata; viene salvata nelle impostazioni del plugin, mai nei tuoi dati di sessione.

Esportare i dati (CSV)#

Tre file CSV: la panoramica dei progetti, la matrice giorno per vault e gli indicatori chiave. Due modi per ottenerli, e finiscono in posti diversi.

Pulsante CSV nell'intestazione della barra laterale: il plugin scrive i file nel tuo vault, nella cartella impostata in Impostazioni → Cartella di esportazione CSV nel vault. Il menu nomina quella cartella prima che tu faccia clic. Le stesse esportazioni sono nella palette dei comandi sotto «Export».

Menu di esportazione CSV della dashboard: la dashboard è una pagina del browser, quindi consegna il file al browser ed è il browser a decidere dove va, di solito la cartella dei download. Una pagina web non può scegliere una cartella di destinazione; è una regola dei browser, non una funzione mancante.

Entrambe le vie producono numeri grezzi e date ISO, pronti per i calcoli in Excel, Sheets o uno script. Tutto viene generato in locale: nessun caricamento, nessuna rete, come nel resto del plugin.

Gli indicatori chiave seguono la stessa regola degli anelli (dalla 2.5): i valori ufficiali della finestra di 5 ore e della settimana con l'ora della lettura, la proiezione settimanale indicata come tale, il limite settimanale che risulta dal feed e l'intervallo dei tuoi limiti raggiunti (il più basso e il più alto). Le vecchie righe con i limiti stimati non ci sono più. Le celle di testo che iniziano con =, +, - o @, come un nome di cartella insolito, ricevono un apostrofo davanti perché Excel o LibreOffice non possano eseguirle come formula; i numeri restano come sono.

Archivio e dati a lungo termine#

Perché esiste. Claude Code gestisce da sé i propri file di sessione locali e li elimina secondo un calendario: 30 giorni di default, regolati da cleanupPeriodDays nel suo ~/.claude/settings.json. Senza una copia altrove, tutto ciò che è più vecchio semplicemente sparisce.

Cosa viene scritto, e dove. Ogni volta che Obsidian è aperto (a ogni aggiornamento, circa ogni 30 secondi, o subito tramite il watcher dei file), il plugin controlla quali giorni recenti hanno già un file d'archivio e ne scrive uno per ogni giorno mancante, compreso oggi, aggiornato durante la giornata. I file finiscono in una normale cartella del tuo vault, uno per giorno: Token Usage Archive/AAAA-MM-GG.md (nome della cartella configurabile nelle impostazioni). Ogni file contiene solo totali: token per tipo, numero di sessioni, volume di token per modello e la ripartizione per vault e progetto di quel giorno, mai un prompt, una risposta o qualcosa che somigli a un contenuto di conversazione.

Una volta scritto, il file di un giorno passato è considerato definitivo e non viene più toccato negli aggiornamenti successivi. L'unica eccezione voluta: quando una versione aggiunge una fonte di dati completamente nuova (le sessioni della modalità agente dell'app desktop sono arrivate così nella v1.8.0), una ricostruzione unica riscrive una volta i giorni recenti interessati, perché i totali incompleti di prima che quella fonte esistesse non restino sbagliati per sempre.

L'archivio si può disattivare del tutto (Impostazioni → Abilita archivio giornaliero) se preferisci che il plugin non crei mai file nel tuo vault; tutto continua a funzionare, ma la portata storica si limita a ciò che Claude Code conserva ancora su disco.

Dashboard e report per vault e progetto#

La barra laterale è pensata per un'occhiata veloce; la dashboard HTML (palette dei comandi → «Open Token Usage dashboard») è pensata per sedersi con i numeri. Rigenera un file HTML statico e lo apre nel browser: un'istantanea, non una connessione in tempo reale, con data e ora indicate onestamente nell'angolo.

Tre schede. Dashboard: i riquadri del budget per la finestra di 5 ore, oggi e la settimana, poi cinque schede di indicatori (Weekly Forecast, Limit Health, Cache Efficiency, Daily Velocity, Focus Score), una barra della settimana, il grafico giornaliero, la distribuzione dei modelli, l'istogramma, Top Sessions e i limiti di utilizzo che hai raggiunto, con il loro intervallo. Reports: gli stessi numeri con la struttura del report in Markdown. Projects: la ripartizione per vault e progetto, più sotto.

La stessa regola della barra laterale (dalla 2.5): i riquadri del budget, la zona complessiva, la scheda Limit Health e il giudizio della barra della settimana usano solo valori ufficiali, con l'ora della lettura, o la proiezione settimanale indicata che ne deriva. Senza il feed i riquadri mostrano i token contati e il tempo fino al reset, e Limit Health rimanda alla configurazione invece di tirare a indovinare. Il Weekly Forecast resta: proietta il tuo consumo contato fino alla fine della settimana di fatturazione, non è un limite.

Il menu del periodo (30/60/180/360 giorni) ricalcola all'istante, nel browser, le schede di riepilogo, il grafico giornaliero e quello della cache; è sempre incorporata una finestra completa di 360 giorni. La distribuzione dei modelli, l'istogramma, Top Sessions e il rilevamento dei limiti di utilizzo restano sulla finestra dei dati in tempo reale, perché l'archivio che alimenta i periodi più lunghi contiene solo totali giornalieri, non quel livello di dettaglio per sessione. Questo vale anche per l'intervallo dei tuoi limiti raggiunti: si misura dai token contati fino a ogni limite, che solo la finestra in tempo reale conserva ancora.

I nomi di cartelle e modelli vengono neutralizzati (dalla 2.5). Il nome del progetto nella dashboard è l'ultima cartella della directory di lavoro in cui è iniziata una sessione. Fino alla 2.1 la dashboard inseriva questi nomi nella pagina senza neutralizzarli, quindi un nome di cartella preparato ad arte, per esempio quello di un repository clonato, avrebbe potuto eseguire codice nella pagina della dashboard nel tuo browser. L'abbiamo trovato nel nostro controllo di sicurezza di ottobre 2026 e non abbiamo alcun indizio che sia mai stato sfruttato. La barra laterale dentro Obsidian non era interessata.

Scheda Projects, per più di un vault o cliente. Ogni riga è una cartella in cui è iniziata una sessione di Claude Code: il tuo vault di Obsidian, il raggruppamento della modalità agente dell'app desktop (mostrato come Claude Desktop (Agent Mode)) o qualsiasi altra directory in cui hai avviato Claude Code direttamente. Le cartelle sotto l'1 % del totale vengono raggruppate in un'unica riga «Other». Spunta «Show sub-project detail» per espandere, direttamente nella tabella, ogni vault la cui directory di lavoro è cambiata durante una sessione; la stessa ripartizione è anche nell'esportazione autonoma Vault_Token_Usage_Projects.md, utile per dividere i costi tra i clienti quando fatturi. Le colonne si ordinano con un clic sull'intestazione.

Comandi di esportazione (palette dei comandi), ognuno sovrascrive il proprio file di destinazione nel vault a ogni esecuzione: Create Token Usage report (Token Usage Report.md), Open Token Usage dashboard (Token Usage Dashboard.html), Create Vault Token Usage Projects report (Vault_Token_Usage_Projects.md). Tutti e tre i percorsi sono configurabili, vedi Riferimento delle impostazioni.

Cosa viene misurato (e cosa no)#

Il plugin copre ogni modo in cui usi Claude Code: terminale, Obsidian, un editor come VS Code e la modalità agente dell'app desktop, tutto confluisce negli stessi numeri (vedi Fonti dei dati e trasparenza per i dettagli). Quello che non può mostrare è la chat normale: le conversazioni nella finestra di chat abituale dell'app desktop di Claude o su claude.ai nel browser. Queste non scrivono mai conteggi di token su disco nel formato che questo plugin legge; l'unico segnale disponibile lì è una percentuale arrotondata del limite del tuo piano. Se una giornata ti sembra più intensa di quanto mostri la dashboard, molto spesso il motivo è questo.

Riferimento delle impostazioni#

Ogni impostazione del plugin, nell'ordine in cui compare in Impostazioni → Token Usage. I valori predefiniti sono scelti perché una nuova installazione funzioni bene senza toccare nulla.

Ogni campo di percorso o cartella ha accanto un pulsante «Mostra nella cartella» che apre la posizione esatta nel gestore di file del tuo sistema.

Prezzi dell'API#

Prezzi dell'API di Anthropic per milione di token, input e output standard, a ottobre 2026:

* Haiku 5.5 per prompt fino a 100.000 token; oltre, 0,50 $ di input / 2,50 $ di output.
** Sonnet 5 è uscito a 2 $ / 10 $ come prezzo di lancio fino al 31 agosto 2026. Anthropic lo ha poi reso il prezzo standard; l'aumento annunciato a 3 $ / 15 $ non c'è stato.

Prezzi della cache in aggiunta al prezzo di input standard:

• C.Write: 1,25 volte il prezzo di input standard del modello per una cache di 5 minuti, 2 volte per una cache di 1 ora (il caso abituale per Claude Code con abbonamento)
• C.Read: 0,1 volte il prezzo di input standard del modello; 0,05 volte su Opus 5.5 e Sonnet 5.5, 0,025 volte su Fable 5.1

Perché i costi si accumulano#

Una singola richiesta raramente è costosa. Calcolo veloce con Sonnet 5 al suo prezzo standard di 2 $ / 10 $ per milione:

• 10.000 token di input × 2 $ / 1M = 0,02 $
• 2.000 token di output × 10 $ / 1M = 0,02 $
• Totale: circa 0,04 $

È quasi niente. Il problema sono la ripetizione e la crescita del contesto. Ogni nuovo messaggio di una sessione di solito rinvia come input la cronologia della conversazione e i file aperti. Dopo dieci scambi, il decimo messaggio porta con sé i nove turni precedenti più i documenti allegati: l'input totale cresce a ogni passo, anche se scrivi solo una breve domanda.

La domanda in sé raramente è ciò che fa salire i costi. Ciò che viaggia con lei, sì.

Cosa fa salire i costi#

• Sessioni lunghe in cui una grande finestra di contesto viene rinviata a ogni richiesta
• File grandi o intere basi di codice allegati, che viaggiano come input con ogni messaggio
• Molte richieste rapide in poco tempo
• Un modello di fascia alta per compiti che uno più economico svolge altrettanto bene

Consigli pratici#

Prima misura. Il grafico giornaliero e la tabella delle sessioni del plugin mostrano dove vanno davvero i token. Non puoi ottimizzare ciò che non hai guardato.

Evita il contesto inutile. I file grandi allegati «per sicurezza» si aggiungono a ogni input. Allega solo ciò che serve a Claude per il compito attuale.

Scegli il modello in base al compito. Non tutte le richieste hanno bisogno di Opus. Le domande veloci, la formattazione e le modifiche semplici al codice spesso vanno bene con Haiku o Sonnet, a una frazione del costo. Confronta la qualità e il costo totale per compito completato, non solo il prezzo per token.

Capisci la cache. Un picco di C.Write all'inizio di una sessione è normale: è stato creato un contesto grande. Ciò che conta è che poi arrivi C.Read. Se lo stesso contesto viene riutilizzato in molte richieste, il costo iniziale di scrittura si ammortizza in fretta e il costo effettivo per richiesta scende molto.

Usa la dashboard. La dashboard HTML (si apre con il pulsante del grafico nella barra laterale) mostra la tua cronologia di utilizzo, 30, 60, 180 o 360 giorni con il selettore del periodo nell'intestazione, oltre alla distribuzione dei modelli e all'andamento dell'efficienza della cache. Guardare i dati su più giorni rivela schemi che la vista di una singola sessione non mostra.

Domande frequenti e risoluzione dei problemi#

Funziona su macOS e Linux, o solo su Windows? Su tutte le piattaforme: il cuore del plugin è sempre stato indipendente dalla piattaforma. L'unico dettaglio specifico è dove la modalità agente di Claude Desktop salva le sue sessioni, una particolarità di Windows; la spiegazione completa è in Fonti dei dati e trasparenza.

«Questa sessione» mostra più token di «Oggi», è un errore? No. Una sessione di Claude Code può superare la mezzanotte, vedi le tre viste temporali sopra.

Perché i miei anelli di 5 ore e della settimana sono grigi, senza percentuale? Dalla 2.5 il plugin mostra una percentuale di limite solo se arriva da Anthropic. Per questo serve il feed facoltativo. Senza, gli anelli mostrano i token contati e il tempo fino al reset, e una breve riga sotto porta alla configurazione. Con un'interrogazione a orari fissi, qualche volta al giorno, l'anello di 5 ore resta comunque grigio per la maggior parte del tempo, perché una lettura di 5 ore vale solo nella finestra in cui è stata presa. Un'interrogazione ogni 30 minuti con --only-when-active cambia le cose. Vedi Limiti: percentuali solo da Anthropic.

Perché la scheda «Limit Health» della dashboard non mostra un valore? Per lo stesso motivo: le serve un valore settimanale ufficiale dal feed. Finché non c'è, la scheda rimanda alla configurazione invece di tirare a indovinare.

Dov'è finito il limite stimato? È stato eliminato nella 2.5 perché sbagliava troppo spesso: per la finestra di 5 ore si discostava in media di 36 punti dai valori ufficiali. Resta l'intervallo in cui la tua finestra di 5 ore si è riempita finora.

La chat nel browser (claude.ai) o la chat normale dell'app desktop non compare da nessuna parte. È previsto, non un errore: vedi Cosa viene misurato e Fonti dei dati e trasparenza sopra.

La revisione dei plugin di Obsidian segnala «Direct Filesystem Access». Devo preoccuparmi? No, quell'avviso è previsto e inevitabile per ciò che fa questo plugin; cosa viene letto e cosa no è spiegato in dettaglio in Fonti dei dati e trasparenza.

I numeri di un giorno sono cambiati dopo l'aggiornamento del plugin. I dati vecchi sono danneggiati? Quasi certamente no: vedi la ricostruzione unica in Archivio e dati a lungo termine.

Posso seguire più di un vault di Obsidian, o dividere l'utilizzo per cliente? Sì, vedi Dashboard e report per vault e progetto.

Mi servono una chiave API o un account Anthropic per usare questo plugin? No. Legge file locali che Claude Code scrive già sul tuo computer.

Ho chiuso Obsidian per qualche settimana. Quel consumo è perso per sempre? Se nel frattempo è uscito dal tuo periodo di conservazione dei dati Claude, sì: vedi il riquadro sul limite onesto in Archivio e dati a lungo termine.

Compatibilità e aggiornamenti di Claude Code#

Token Usage legge i file di sessione JSONL che Claude Code scrive in locale. Anthropic aggiorna Claude Code regolarmente, a volte in modi che influiscono su come vengono registrati i dati di sessione o su come viene contata la telemetria interna.

Esaminiamo le note di rilascio di Anthropic a ogni versione importante di Claude Code e adattiamo il plugin quando serve. Le modifiche di compatibilità rilevanti sono documentate nel changelog del plugin su GitHub.

Informazioni su questo plugin#

Token Usage è un plugin open source della community di Obsidian. Legge i file JSONL locali scritti da Claude Code; nessun dato viene inviato da nessuna parte. Manca qualcosa in questa pagina? Issue e richieste di funzionalità sono sempre benvenute.

• GitHub: beolatn/TokenUsage
• Directory dei plugin di Obsidian: Token Usage
• Autore: Björn-Olaf Lange · langeatn.de

I prezzi citati in questa pagina provengono dalla documentazione ufficiale di Anthropic. Ultimo aggiornamento: ottobre 2026. I prezzi possono cambiare; controlla sempre le tariffe attuali sul sito di Anthropic.