Che cos'è Auto Compact in Claude Code

Claude Code è l’assistente di coding agentico di Anthropic che può leggere una base di codice, modificare file, eseguire comandi e integrarsi con strumenti nei flussi di lavoro su terminale, IDE, app desktop e browser. Poiché lavora dentro una finestra di contesto condivisa, le sessioni lunghe alla fine si riempiono di cronologia chat, output di file e “chiacchiericcio” degli strumenti. Claude Code gestisce questo automaticamente compattando la cronologia della conversazione quando ti avvicini al limite, e le istruzioni iniziali possono andare perse se compaiono solo nella cronologia chat.

Questo è ancora più importante nel 2026 perché Anthropic continua a spingere Claude Code verso lavori più lunghi e più autonomi. Il 25 marzo 2026, Anthropic ha pubblicato “Claude Code auto mode: a safer way to skip permissions”, affermando che gli utenti approvano il 93% delle richieste di autorizzazione e descrivendo l’auto mode come una via di mezzo basata su classificatore tra approvazione manuale e salto non sicuro delle autorizzazioni. Il 5 febbraio 2026, Anthropic ha anche lanciato Claude Opus 4.6, evidenziando capacità di coding più forti, debugging migliore e sessioni agentiche più lunghe. Questi aggiornamenti non sono la stessa cosa dell’auto compact, ma mostrano chiaramente la direzione del prodotto: meno interruzioni, sessioni più lunghe e continuità più affidabile.

CometAPI attualmente offre accesso alla Claude API a un prezzo inferiore rispetto all’API ufficiale, per esempio Claude Sonnet 4.6, Claude Opus 4.6, e la Claude 5.

Cosa significa davvero auto-compact in Claude Code

Auto Compact è un meccanismo integrato di ottimizzazione del contesto in Claude Code (lo strumento CLI/desktop di Anthropic) e nel più ampio ecosistema della Claude API. Interviene automaticamente quando la conversazione si avvicina al limite della finestra di contesto del modello—tipicamente intorno a 200.000 token per i modelli di punta come Claude Opus 4 o Sonnet 4. La documentazione degli hook è esplicita: PreCompact si attiva prima di un’operazione di compattazione, e il matcher auto significa “auto-compact quando la finestra di contesto è piena.” L’hook corrispondente PostCompact si attiva dopo il completamento della compattazione e riceve il compact_summary generato.

Questo è importante perché la compattazione non è la stessa cosa della “memoria”. Auto memory è il sistema di annotazioni proprio di Claude, mentre la compattazione è un meccanismo di gestione della sessione che comprime lo stato della conversazione in tempo reale. I documenti sulla memoria chiariscono che CLAUDE.md è persistente, l’Auto memory è scritta da Claude, e la compattazione è il momento in cui la cronologia conversazionale della sessione viene ridotta così che il modello possa continuare a lavorare.

Invece di forzare una nuova chat (e perdere la cronologia) o lasciare che il modello “dimentichi” dettagli critici, Auto Compact:

1. Analizza l’intera cronologia — identificando gli elementi chiave da conservare.
2. Genera un riepilogo conciso — di decisioni, architettura del codice, bug risolti, stato dei file e prossimi passi.
3. Sostituisce i messaggi più vecchi — con questo riepilogo (un “compaction block” in termini API).
4. Riprende senza interruzioni — con il contesto preservato.

Dati chiave (2026):

• Soglia di attivazione: predefinita a ~95% della capacità (o ~25% rimanente). Alcuni utenti segnalano un buffer interno che riserva 20–45k token (~22,5% del contesto) per il processo di compattazione stesso.
• Miglioramento delle prestazioni: da Claude Code v2.0.64, la compattazione è “istantanea” invece di richiedere minuti.
• Esempio di risparmio di token (dai benchmark del Claude Agent SDK): Un workflow di 5 ticket è sceso da 204k a 82k token in input (riduzione del 58,6%) con due eventi di compattazione.

Auto Compact non è lo stesso di /clear (che cancella tutto) o di un semplice troncamento. Preserva in modo intelligente ciò che conta—diff recenti del codice, scelte architetturali, convenzioni di denominazione—mentre condensa i loop di debugging risolti e le digressioni esplorative.

Perché usare Auto Compact in Claude Code?

Le sessioni di coding lunghe sono la norma. Una singola implementazione di una feature può durare 50+ turni: pianificazione, debugging, refactoring, test. Senza compattazione, l’uso di token cresce linearmente, la qualità delle risposte degrada e i costi esplodono.

Per gli sviluppatori, il vantaggio è meno fatica da riavvio. Invece di copiare manualmente un riepilogo in una nuova sessione, lasci che Claude compatti la sessione e continui. Questo è particolarmente utile nel bug-fixing, nei refactor multi-file, nei cambiamenti guidati dai test e nei workflow ricchi di review in cui la conversazione può diventare molto lunga. Le sessioni di Claude Code iniziano con una nuova finestra di contesto, quindi la compattazione è uno dei meccanismi chiave che rende pratico il lavoro di lunga durata.

Benefici principali

• Lunghezza di sessione illimitata: Continua indefinitamente senza ricominciare da capo.
• Efficienza in costi e prestazioni: Riduce drasticamente i token in input. Report reali mostrano risparmi del 50–60% in workflow multi-fase.
• Maggior focus e stabilità: Previene il “sovraccarico di contesto” in cui il modello allucina o dimentica vincoli precedenti.
• Conserva la conoscenza istituzionale: Decisioni chiave restano nel contesto anche dopo centinaia di messaggi.
• Senza attriti per i workflow agentici: Critico quando si usano strumenti, server MCP o setup multi-agente in Claude Code.

Quando dovresti fare affidamento su auto compact?

Usa Auto Compact quando il compito è per natura di lunga durata: refactor multi-file, sessioni di debugging tra log e sorgenti, implementazione di feature con verifiche ripetute, o ricerche che richiedono molte chiamate strumenti. La documentazione di Anthropic punta esplicitamente a sessioni lunghe in cui la finestra di contesto si riempie di conversazioni irrilevanti, contenuti di file e comandi, e afferma che l’auto compattazione preserva codice e decisioni chiave liberando spazio.

È meno adatto quando il compito è breve, isolato o richiede istruzioni precise e da conservare in modo permanente. Quelle istruzioni presenti all’inizio della conversazione possono andare perse dopo la compattazione, motivo per cui le regole di progetto dovrebbero stare in CLAUDE.md, non in un prompt usa e getta che potrebbe essere compresso via in seguito.

Quando usarlo (o abilitarlo):

• Sempre attivo per impostazione predefinita per la maggior parte degli utenti — ideale per coding quotidiano, grandi refactor o progetti esplorativi.
• Compiti di lunga durata — elaborazione di code, pipeline di dati o codebase multi-file.
• Ambienti team/enterprise — dove la continuità del contesto tra le sessioni è importante.
• Progetti ad alta criticità — dove perdere una singola decisione architetturale potrebbe costare ore.

Quando considerare di disabilitarlo (via /config):

• Vuoi ogni singolo token di contesto per un controllo ultra-preciso.
• Preferisci una gestione completamente manuale (power user che salvano/ripristinano piani via file).

Novità (2025–2026): A marzo 2025, Anthropic ha migliorato la logica di preservazione di Auto Compact, rendendo i riepiloghi più intelligenti nel trattenere “informazioni importanti riducendo l’uso di token.” Entro fine 2025, il triggering è stato raffinato (a volte anticipato al 64–75% di utilizzo per evitare compattazioni fallite). Gli inizi del 2026 hanno visto bug temporanei nelle interfacce web/desktop (segnati come risolti a metà gennaio ma con segnalazioni residue), mentre la CLI è rimasta stabile. La versione 2.0.64 (feb 2026) ha reso la compattazione istantanea, un grande vantaggio per l’esperienza sviluppatore.

Come usare Auto Compact in Claude Code: guida passo-passo

Claude Code è progettato in modo che ogni sessione inizi con una nuova finestra di contesto. Questo è utile perché ogni nuovo compito parte pulito, e rende anche più facile capire quando una sessione sta diventando rumorosa. Si consiglia /clear tra compiti non correlati così il contesto obsoleto non continua a occupare spazio.

Step 1: Verifica lo stato attuale del contesto

Usa /context per visualizzare il carico del contesto attuale. L’elenco dei comandi integrati di Claude Code indica che /context mostra una griglia colorata ed evidenzia l’ingombro di memoria, suggerimenti di ottimizzazione e avvisi di capacità. È il modo più rapido per capire se ti stai avvicinando al punto in cui l’auto compattazione probabilmente scatterà.

Nella tua sessione di Claude Code, digita:

/context

Questo mostra “Context left until auto-compact: XX%” — la tua barra di avanzamento in tempo reale.

Step 2: Configura Auto-Compact (opzionale)

Quando la finestra di contesto si riempie, Claude Code compatta automaticamente la conversazione. La reference degli hook etichetta questo evento come auto, e si attiva quando la finestra di contesto è piena. In pratica, non “attivi” Auto Compact quanto piuttosto lasci che Claude Code lo esegua quando necessario.

/config

Vai su “Auto-compact enabled” e attiva/disattiva true/false. Il default è abilitato. Puoi anche regolare impostazioni correlate, come l’uso dei server MCP, per liberare token in modo proattivo.

Step 3: Lascia che Auto-Compact si avvii automaticamente

Quando raggiungi ~95%:

• Claude visualizza “Compacting our conversation so we can keep chatting…” (o simile).
• Esegue in background e riprende.
• Vedrai il nuovo riepilogo in cima al contesto.

Suggerimento: Non aspettare lo 0%. Compatta manualmente prima per risultati migliori (vedi best practice sotto).

Step 4: Usa gli hook se vuoi automatizzare cosa succede attorno alla compattazione

Claude Code espone sia gli hook PreCompact sia PostCompact. La reference degli hook mostra che PreCompact può rilevare se la compattazione è manuale o automatica, e PostCompact riceve il compact_summary generato. Questo rende gli hook molto adatti per logging, audit trail, note post-compattazione o automazioni esterne.

Un semplice pattern di hook è il seguente:

{  "hooks": {    "PostCompact": [      {        "matcher": "auto",        "hooks": [          {            "type": "command",            "command": "./scripts/save-compact-summary.sh"          }        ]      }    ]  }}

E lo script shell corrispondente può leggere l’input JSON da stdin, perché gli hook di comando di Claude Code ricevono JSON in quel modo:

#!/usr/bin/env bashset -euo pipefailjq -r '.compact_summary // empty' \  | sed 's/^/[compact] /' \  >> .claude/compact-log.txt

I documenti confermano che i command hook ricevono JSON via stdin e che PostCompact include compact_summary, quindi questo pattern è allineato con il modello di hook attuale.

Step 5: Compattazione manuale con precisione (consigliata)

Usa /compact quando vuoi che l’assistente comprima il thread subito. Puoi includere istruzioni che plasmano il riepilogo che vuoi preservare. La pagina dei comandi integrati di Anthropic elenca /compact [instructions] come “Compatta la conversazione con istruzioni opzionali di focus,”

/compact keep the auth flow decisions, the current test plan, and the open TODOs

Questo pattern è utile prima di un handoff, prima di un cambio di branch, o prima di chiedere a Claude di iniziare una nuova fase di lavoro.

Esempi dall’uso reale:

• Dopo il debugging: /compact keep the solution we found, remove debugging steps
• Milestone di progetto: /compact focus on the new feature requirements

Compattazione a livello di API (avanzato – Python SDK e Messages API)

Per agent personalizzati o script, usa gli strumenti ufficiali di compattazione.

Esempio con Claude Agent Python SDK (automatico per workflow che usano strumenti):

from anthropic import Anthropic

client = Anthropic()

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=your_tools,
    messages=messages,
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,  # or lower for aggressive compaction
        "model": "claude-haiku-4-5",        # cheaper summarizer
        "summary_prompt": """Create a focused summary preserving:
1. COMPLETED TASKS and key outcomes
2. CURRENT STATE and open items
3. NEXT STEPS
Wrap in <summary></summary> tags."""
    }
)

Rileva eventi di compattazione:

if curr_msg_count < prev_msg_count:
    print(f"Compaction occurred! Messages reduced from {prev_msg_count} to {curr_msg_count}")
```<grok-card data-id="f4afb5" data-type="citation_card" data-plain-type="render_inline_citation" ></grok-card>

Full Messages API (beta, 2026) – richiede header:
```bash
curl https://api.anthropic.com/v1/messages \
  --header "anthropic-beta: compact-2026-01-12" \
  --data '{
    "model": "claude-opus-4-6",
    "messages": [...],
    "context_management": {
      "edits": [{
        "type": "compact_20260112",
        "trigger": {"type": "input_tokens", "value": 150000},
        "pause_after_compaction": true
      }]
    }
  }'

L’API restituisce un blocco di compattazione che devi passare nelle chiamate future. Istruzioni personalizzate e pausa danno pieno controllo sul budgeting (ad es., imporre un tetto totale di 3M token tra sessioni).

Se stai usando la Claude API di CometAPI, cambia l’header del messaggio in "https://api.cometapi.com/v1/messages\\".

Auto-Compact vs Manual Compact vs Clear: tabella di confronto

Best practice per Auto Compact in Claude Code (consigli dei developer)

Compatta in modo proattivo

La terza regola è usare la compattazione come un reset, non una stampella. Se il thread è pieno di vicoli ciechi, chiedi a Claude di compattare con un’istruzione chiara su ciò che conta: obiettivo attuale, approccio scelto, test falliti e questioni irrisolte. In pratica, questo rende il riepilogo molto più utile che lasciare che il sistema compatti alla cieca sperando nel meglio.

Mantieni brevi le istruzioni durevoli.

Anthropic afferma che file oltre 200 righe possono ridurre l’aderenza, quindi grossi blocchi di policy sono di solito peggiori di regole concise e ben circoscritte. Usa .claude/rules/ per comportamento specifico per tipo di file o percorso, e usa le importazioni @path quando ti servono dettagli di supporto più ricchi senza appesantire il file principale delle istruzioni.
Free tokens first — Disabilita i server MCP inutilizzati con /mcp o @server-name disable prima di compattare.

Combina con CLAUDE.md

Tratta CLAUDE.md come la fonte di verità per tutto ciò che vuoi che sopravviva a una long sessionCLAUDE.md viene riletto dopo /compact, il che lo rende il posto giusto per i comandi di build, le convenzioni di coding e le regole persistenti che non vuoi mai perdere. Auto memory è utile anche, ma è un sistema diverso con uno scopo diverso.

Altri suggerimenti

Monitora con /context — Tieni l’uso sotto il 70–80% quando possibile.

Per gli utenti API — Imposta soglie più basse (ad es., 50k–100k) e usa modelli riassuntivi più economici come Haiku.

Disabilita solo quando necessario — La maggior parte degli sviluppatori ora consiglia di tenere Auto-Compact attivo dopo i miglioramenti del 2025.

Testa la compattazione — Prima in sessioni non critiche per vedere come viene riassunto il tuo workflow specifico.

Impatto reale: Gli sviluppatori riportano sessioni produttive 2–3x più lunghe e meno momenti in cui “Claude ha dimenticato cosa stavamo facendo.”

Problemi comuni e troubleshooting (edizione 2026)

• Auto-compact non si attiva: Controlla web/desktop vs CLI; alcuni bug di gennaio 2026 sono stati risolti ma verifica la versione.
• Contesto perso dopo la compattazione: Usa la compattazione manuale /compact con istruzioni esplicite la prossima volta.
• Loop infiniti o uso al 102%: Raro; riavvia la sessione o usa /clear come ultima risorsa.
• Compattazione lenta: Problema pre-v2.0.64—aggiorna Claude Code.
• Errori del compaction block API: Allega sempre l’intero blocco di compattazione nelle chiamate successive.

Conclusione

L’auto compattazione è uno dei meccanismi nascosti più importanti in Claude Code perché mantiene utilizzabili le sessioni di coding lunghe senza costringerti a riavviare ogni volta che la finestra di contesto si riempie. La regola pratica è semplice: lascia che Auto Compact gestisca l’overflow, usa /compact quando vuoi controllo, conserva le indicazioni durevoli in CLAUDE.md, e usa /clear o /rewind quando cambia la struttura della sessione. Questa combinazione offre il miglior equilibrio tra continuità, controllo e velocità nei workflow lunghi con Claude Code.

Auto Compact in Claude Code rappresenta un salto nello sviluppo assistito dall’AI in pratica. Gestendo in modo intelligente la finestra di contesto da 200k token, elimina il principale punto di attrito nel coding di lunga durata: esaurire la memoria. Con prestazioni istantanee (2026), ricche opzioni di configurazione e potenti estensioni API, è ora una funzionalità matura e collaudata, usata quotidianamente da migliaia di sviluppatori.

Azioni da fare oggi:

1. Apri Claude Code ed esegui /config — conferma che Auto-Compact sia abilitato.
2. Prova una /compact manuale con istruzioni sul tuo progetto attuale.
3. Esplora il Python SDK o la Messages API per agent automatizzati in CometAPI.