Claude Code lento e costoso: come ridurre il contesto

Come evitare che una sessione lunga di Claude Code diventi lenta e costosa

Una sessione lunga di Claude Code diventa lenta e costosa perché a ogni turno viene reinviato l’intero contesto, che continua a crescere. La soluzione è applicare una procedura di pulizia in un ordine prestabilito. Esegui /context per vedere quali elementi occupano la finestra di contesto, riduci quelli che vengono conteggiati a ogni richiesta, quindi usa /clear tra attività non correlate e /compact con un’istruzione all’interno di un’unica attività lunga. Lavora per sessioni continue, perché una cache del prompt fredda trasforma una lettura economica in una riscrittura completa di tutto ciò che hai detto.

Il motivo per cui il contatore aumenta è spiegato in il contatore dei token alla base di una sessione agent.

Leggi /context prima di modificare qualsiasi cosa

Non indovinare cosa riempie la finestra. Claude Code te lo comunicherà.

/context [all] mostra l'utilizzo attuale del contesto sotto forma di griglia colorata, con suggerimenti per l'ottimizzazione degli strumenti che usano molto contesto e della crescita eccessiva della memoria; all espande la suddivisione per elemento in modalità a schermo intero. Interpreta il risultato come cinque categorie.

• Il prompt di sistema. Le istruzioni del framework di Claude Code. Sono fisse per la sessione.
• Le definizioni degli strumenti. Lo schema di ogni strumento che l'agente può chiamare, inclusi tutti i server MCP (Model Context Protocol) connessi.
• I file di memoria. CLAUDE.md e la memoria automatica, caricati all'avvio della sessione.
• I file e i risultati degli strumenti. Ogni file letto e tutto ciò che i comandi restituiscono.
• La cronologia dei messaggi. I tuoi turni e le relative risposte.

I primi tre elementi costituiscono un costo fisso, sostenuto a ogni richiesta per tutta la durata della sessione. Gli ultimi due aumentano nel tempo. Riduci il costo fisso una volta, all'inizio; gestisci continuamente la parte crescente.

Due stringhe indicano che la finestra è piena:

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

La prima indica un limite rigido: la richiesta viene rifiutata e l'errore dell'API (application programming interface) corrispondente è Prompt is too long. La seconda indica una finestra di compattazione, che può essere inferiore alla finestra di contesto effettiva su un modello da 1 million di token. Le richieste continuano ad avere esito positivo oltre questa soglia, quindi si tratta di un avviso e non di un rifiuto.

Con un piano a pagamento, /usage aggiunge l'altra metà del monitoraggio: segnala comportamenti come l'uso di un contesto esteso o i cache miss e attribuisce l'utilizzo recente a singole competenze, sottoagenti e server MCP. Se indica che la quota è già esaurita, quale finestra del limite stai aspettando determina se ridurre il contesto ti aiuta subito o se devi seguire un percorso diverso per riprendere il lavoro.

CLAUDE.md è un costo permanente, quindi mantienilo essenziale

Il tuo CLAUDE.md viene caricato all'avvio della sessione e rimane nel contesto. Se contiene una procedura di deployment dettagliata, quei token restano presenti mentre correggi un refuso in un file di test. Le indicazioni di Anthropic raccomandano di includere solo gli elementi essenziali e di mantenere il file sotto le 200 righe.

Sposta le procedure nelle skill. Una skill viene caricata solo quando viene invocata, quindi un workflow eseguito due volte alla settimana non comporta alcun costo negli altri giorni. Dopo una compattazione, le skill dispongono di un budget dedicato: il contenuto viene reiniettato, con un limite di 5.000 token per skill e 25.000 token complessivi; le skill più vecchie vengono rimosse per prime. Il troncamento mantiene l'inizio del file, quindi inserisci le istruzioni più importanti vicino all'inizio di SKILL.md.

Ciò che sopravvive a una compattazione determina la posizione corretta di un'istruzione.

• Il prompt di sistema e lo stile di output restano invariati, perché non fanno parte della cronologia dei messaggi.
• Il CLAUDE.md nella radice del progetto, le regole senza ambito e la memoria automatica vengono reiniettati dal disco.
• Una regola con frontmatter paths: viene persa finché non viene letto di nuovo un file corrispondente.
• Un CLAUDE.md annidato in una sottodirectory viene perso finché non viene letto di nuovo un file in quella sottodirectory.
• Gli hook non sono interessati, perché un hook viene eseguito come codice e non entra mai nel contesto.

Pertanto, una regola da cui dipendi deve trovarsi nel CLAUDE.md nella radice del progetto: Claude Code elimina prima gli output degli strumenti più vecchi e poi crea un riepilogo, quindi le istruzioni delle prime fasi della conversazione possono andare perse. Modifica la memoria con /memory. Claude Code mantiene la copia caricata all'avvio della sessione, quindi un'operazione di riduzione durante la sessione conserva la cache del prompt e non ha effetto fino al successivo /clear, /compact o riavvio. La perdita di contesto è solo uno dei motivi per cui una regola può non essere più rispettata; quindi, quando la regola è chiaramente ancora nella finestra di contesto ma viene comunque ignorata, esamina le altre cause prima di riscriverla.

clear tra le attività, compact all'interno della stessa

Questi due comandi sembrano intercambiabili, ma hanno costi molto diversi.

/clear [name] avvia una nuova conversazione con il contesto vuoto. Non invia alcuna richiesta, quindi non ha costi. Passa un nome per etichettare la conversazione precedente nel selettore /resume; /reset e /new sono alias. Usalo appena passi a un'attività non correlata, perché altrimenti l'attività precedente verrebbe reinviata e fatturata di nuovo a ogni messaggio della nuova attività.

/compact [instructions] libera spazio nel contesto continuando la stessa conversazione: riassume la cronologia disponibile e la sostituisce. Usalo all'interno di un'attività lunga, quando hai ancora bisogno della continuità.

Dai sempre a /compact un'istruzione. Un /compact senza argomenti genera un riepilogo usando un prompt predefinito, che non sa quale parte del lavoro ti serve ancora. Un comando con istruzioni conserva questo contesto:

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Se usi compact ogni volta per lo stesso motivo, inserisci un'istruzione permanente nel CLAUDE.md del progetto, sotto un'intestazione # Compact instructions. In una nuova sessione, /compact stampa Not enough messages to compact., che significa soltanto che non esiste ancora una cronologia.

Qui vengono confusi due costi. La richiesta di riepilogo condivide il prefisso, quindi legge la cache esistente invece di rielaborare la cronologia; la maggior parte del tempo viene impiegata per generare il riepilogo. Compattare un contesto grande resta una richiesta grande, perché la conversazione da riassumere costituisce l'input. Il turno successivo alla compattazione non è la parte lenta: ricostruisce la cache usando un prompt molto più breve.

Esistono due comandi più economici. /rewind [description] ripristina il codice e la conversazione a un checkpoint; per un percorso che vuoi abbandonare completamente è preferibile a compact, perché tronca la conversazione fino a un prefisso già presente nella cache. /recap aggiunge un riepilogo come output del comando invece di sostituire la cronologia, quindi il prefisso memorizzato nella cache resta intatto.

Quando la compattazione automatica si attiva ripetutamente, viene visualizzato questo messaggio:

Autocompact is thrashing: the context refilled to the limit...

La compattazione è riuscita, ma un file o l'output di uno strumento ha riempito nuovamente la finestra diverse volte consecutive, quindi Claude Code ha smesso di riprovare. Per risolvere il problema, leggi il file troppo grande per intervalli di righe, esegui /compact con un focus che escluda l'output di grandi dimensioni, sposta l'attività a un subagent oppure usa /clear se la conversazione precedente è conclusa.

I server MCP hanno un overhead fisso

Ogni server MCP a cui ti connetti contribuisce a ogni richiesta per l'intera sessione. Il costo si applica anche se non lo utilizzi.

Claude Code riduce questo effetto. Per impostazione predefinita, le definizioni degli strumenti MCP vengono caricate in modo differito: nel contesto entrano soltanto i nomi degli strumenti, finché Claude non ne utilizza uno specifico. Esegui /context per verificare il costo effettivo dei server ed esegui /mcp disable <name> per rimuovere quello che non utilizzerai oggi. Se esegui server MCP personali su un VPS, lo stesso calcolo determina quanti strumenti dovrebbe esporre un singolo server.

Esegui questa operazione all'inizio della sessione. Finché le definizioni restano differite, connettere o disconnettere un server aggiunge soltanto contenuto alla conversazione e la cache rimane disponibile. Se invece le definizioni vengono caricate nel prefisso, perché la ricerca degli strumenti è disabilitata o un server non utilizza il caricamento differito, la stessa modifica fa rileggere tutto nella richiesta successiva.

Filtra l'output dettagliato degli strumenti prima che entri nel contesto

Il risultato di uno strumento è un input e viene reinviato a ogni turno successivo. Un'esecuzione di test che produce 20.000 token di output non ha un costo una tantum: paghi di nuovo per quell'output a ogni turno, finché non esce dalla finestra di contesto.

Filtra alla fonte. Un hook che riduce un'esecuzione di test ai soli errori prima che Claude la visualizzi trasforma quell'output molto esteso in poche centinaia di token, in questo turno e a ogni suo reinvio:

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Gli hook non entrano direttamente nel contesto, perché vengono eseguiti come codice. Applica questa tecnica a qualsiasi strumento il cui output superi una schermata. La stessa logica vale per un file di 3.000 righe: richiedi l'intervallo di righe necessario, perché l'intero file rimane nella finestra di contesto una volta ricevuto.

Definisci l’ambito dei file letti dall’agente e delega le attività rumorose

Un prompt che indica il file e il sintomo legge quel file. Una richiesta generica di riordinare il progetto porta l’agente a leggere tutti i file che ritiene pertinenti, e ogni lettura rimane nella finestra di contesto.

Delega le attività che producono molto output a un subagent. Le esecuzioni dei test e l’elaborazione dei log consumano entrambe contesto reale; un subagent mantiene quell’output nella propria finestra e restituisce solo un riepilogo. Il compromesso è il seguente: un subagent crea la propria cache, che alla prima chiamata non contiene hit, e utilizza la durata della cache di cinque minuti anche con un abbonamento. La delega protegge in modo affidabile il contesto principale. Non riduce sempre il numero totale di token.

La cache ha una durata: lavora per sessioni consecutive

Il caching dei prompt rende conveniente il reinvio: leggere il prefisso costa 0.1x della tariffa base per gli input, mentre scriverlo costa 1.25x, oppure 2x se si sceglie la durata di un'ora. Ogni utilizzo rinnova la voce senza costi aggiuntivi, quindi il conteggio riparte dall'ultimo utilizzo. Questi moltiplicatori indicano la struttura del costo, ma non il suo importo; abbinali quindi a quanto costa realmente un milione di token per convertire una finestra di contesto completa in un importo in dollari.

La durata disponibile dipende dal metodo di autenticazione. Per questo, l'affermazione generica «la cache scade dopo cinque minuti» è errata.

• Con un abbonamento Claude, Claude Code richiede automaticamente la durata di un'ora.
• Dopo aver superato il limite del piano e aver iniziato a utilizzare i crediti di consumo, l'utilizzo viene fatturato e la durata torna a cinque minuti.
• Con una API key o con un cloud provider, la durata resta di cinque minuti. ENABLE_PROMPT_CACHING_1H=1 seleziona la durata di un'ora, mentre FORCE_PROMPT_CACHING_5M=1 la forza nuovamente a cinque minuti.

Il consiglio operativo è lo stesso in entrambi i casi: lavora in sessioni continue, perché una pausa superiore alla durata della cache fa riscrivere interamente il prefisso accumulato alla richiesta successiva. Una sessione Claude Code scollegata in tmux non comporta costi mentre è inattiva; il tempo di inattività viene però sottratto alla durata della cache attiva.

Alcune azioni eliminano la cache anche se la sessione è ancora in corso: cambiare modello, modificare il livello di effort, attivare la fast mode, connettere o disconnettere un server MCP, abilitare o disabilitare un plugin, negare un intero tool, eseguire il compacting e aggiornare Claude Code. /model è la sorpresa più comune, perché ogni modello dispone di una cache distinta. La richiesta successiva deve quindi rileggere l'intera cronologia senza cache hit, anche se il contenuto è identico. Questa rilettura viene fatturata alle tariffe del modello di destinazione; perciò, passare a Fable durante una sessione addebita l'intera cronologia accumulata alla tariffa pubblicata per gli input di Fable 5.

Modificare file, modificare CLAUDE.md, invocare skills e commands, eseguire /recap, eseguire un rewind e avviare un subagent mantengono la cache. La cache è associata a una sola macchina e a una sola directory, quindi due sessioni in directory diverse non possono utilizzare la cache dell'altra. Questo ambito segue la CLI e non l'account. Di conseguenza, i dati non vengono trasferiti all'app desktop Claude, che su Linux è un'installazione beta separata dalla CLI.

Per verificare se il caching funziona, consulta current_usage. cache_creation_input_tokens è stato scritto alla tariffa di scrittura della cache; cache_read_input_tokens è stato fornito a una tariffa pari a circa un decimo di quella standard per gli input. Un rapporto elevato tra letture e creazioni indica un funzionamento corretto. Se il costo di creazione resta elevato a ogni turno, significa che qualcosa nel prefisso continua a cambiare.

Una finestra di contesto più ampia risolve il problema?

In parte. Diversi modelli attuali supportano una finestra di contesto da 1 milione di token e la compattazione funziona allo stesso modo anche con questo limite più elevato. L'impatto economico non cambia, perché il prompt completo viene comunque reinviato e addebitato a ogni turno. Una finestra più ampia stabilisce quando sei costretto a intervenire; una buona gestione del contesto determina i costi. Se il problema è il costo e non il limite, quale piano Claude si adatta al tuo modo di lavorare determina se stai spendendo dollari o utilizzando la quota del piano.

La modifica e la compattazione del contesto nell'API sono funzionalità diverse

Se stai creando un tuo agent con la Messages API, non esistono comandi slash e devi implementare questa logica autonomamente. Prevedi questo lavoro fin dall'inizio, perché l'API non offre un piano gratuito oltre a un piccolo credito di registrazione: ogni turno della cronologia non ridotta viene addebitato per intero. Il provider scelto determina questo calcolo prima di qualsiasi riduzione; se la scelta è ancora aperta, calcola il costo dello stesso carico di lavoro su entrambe le API invece di confrontare soltanto le tariffe pubblicizzate per token. Due funzionalità lato server svolgono questo compito, ma non sono equivalenti.

La modifica del contesto elimina selettivamente contenuti specifici dalla cronologia della conversazione man mano che cresce e sostituisce ogni contenuto eliminato con testo segnaposto, in modo che Claude sappia che qualcosa è stato rimosso. È una funzionalità beta: invia anthropic-beta: context-management-2025-06-27 e configura le strategie in context_management.edits. clear_tool_uses_20250919 elimina i risultati degli strumenti e clear_thinking_20251015 gestisce i blocchi di ragionamento. Il valore predefinito di trigger è 100,000 token di input, quello di keep è rappresentato dagli ultimi 3 utilizzi degli strumenti e quello di clear_tool_inputs è false; gli input vengono quindi mantenuti e vengono eliminati soltanto i risultati.

La compattazione genera un riepilogo e sostituisce con esso l'intera cronologia della conversazione. Anche questa è una funzionalità beta: invia anthropic-beta: compact-2026-01-12 e usa il tipo di modifica compact_20260112. Il valore predefinito del trigger è {"type": "input_tokens", "value": 150000} e il valore deve essere almeno 50,000.

La compattazione prevede una regola di passaggio al turno successivo che può causare errori non evidenti negli agent. La risposta inizia con un blocco di contenuto compaction che contiene il riepilogo, seguito dal normale blocco di testo. Devi reinviare quel blocco nelle richieste successive; l'API elimina quindi ogni blocco di contenuto precedente. In pratica, aggiungi tutto response.content, non soltanto il testo.

La documentazione di Anthropic indica la compattazione lato server come strategia principale per gestire il contesto nelle conversazioni di lunga durata e la modifica del contesto come opzione per controllare con maggiore precisione ciò che viene eliminato. Verifica prima il supporto del modello. Gli attuali modelli Opus, Sonnet e Fable supportano la compattazione; claude-haiku-4-5 non la supporta e la pagina dedicata alla compattazione contiene l'elenco aggiornato. Nessuna delle due funzionalità beta controlla il /compact di Claude Code, che la relativa documentazione descrive come una richiesta di riepilogo singola inviata dal client.

FAQ

Perché la sessione di Claude Code diventa più lenta e costosa quanto più a lungo rimane attiva?

Perché a ogni turno viene inviata di nuovo l'intera conversazione. Di conseguenza, una domanda di una riga in una sessione aperta per tutta la giornata include tutto il contenuto accumulato durante la giornata. La memorizzazione nella cache dei prompt mantiene basso il costo finché la cache è valida, applicando una tariffa pari a 0.1x della tariffa base di input per una lettura. Quando un turno non trova una corrispondenza nella cache, lo stesso prefisso viene memorizzato di nuovo a 1.25x. Esegui /context per vedere quali elementi stanno occupando la finestra di contesto e leggi per cosa viene addebitato il costo di una sessione di Claude Code per capire il meccanismo.

Qual è la differenza tra /clear e /compact in Claude Code?

/clear avvia una nuova conversazione con un contesto vuoto. Non invia alcuna richiesta, quindi non ha costi, ed è la scelta corretta tra attività non correlate. /compact mantiene la stessa conversazione e sostituisce la cronologia con un riepilogo, quindi è la scelta corretta all'interno di un'unica attività lunga. Specifica un obiettivo, come in /compact keep only the plan and the diff, perché l'istruzione determina quali informazioni vengono mantenute.

Come posso vedere che cosa sta occupando la finestra di contesto di Claude Code?

Esegui /context oppure /context all per ottenere la suddivisione completa per elemento. Il comando mostra il prompt di sistema, le definizioni degli strumenti, i server MCP, i file di memoria e la cronologia in una griglia a colori, con suggerimenti sugli strumenti che consumano molto contesto e sull'eccesso di dati nei file di memoria. Con un piano a pagamento, /usage attribuisce inoltre l'utilizzo recente alle singole skill, ai subagent e ai server MCP.

Devo usare una finestra di contesto da 1 milione di token invece di eseguire la compaction?

Una finestra più grande rimanda il problema, ma non lo risolve. Diversi modelli attuali usano una finestra di contesto da 1 milione di token, tra cui Opus 4.8 e Sonnet 5, e la compaction si comporta nello stesso modo anche in questo caso. A ogni turno l'intero prompt viene comunque inviato di nuovo e viene comunque conteggiato, quindi una conversazione da 400,000 token è costosa indipendentemente dal fatto che rientri nella finestra.

Qual è la differenza tra context editing e compaction nella Claude API?

Il context editing cancella selettivamente i contenuti meno recenti, soprattutto i risultati degli strumenti, lasciando al posto di ciascuno un testo segnaposto che informa Claude della relativa rimozione. La compaction genera un riepilogo e sostituisce con esso l'intera cronologia. La documentazione di Anthropic indica la compaction come strategia principale per le conversazioni lunghe e presenta il context editing come opzione più granulare. Entrambe le funzioni sono in versione beta e richiedono header specifici; inoltre, sono separate da /compact di Claude Code.