SpyBara
Go Premium

checkpointing.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 29 additions and 19 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Checkpointing

Traccia, riavvolgi e riassumi le modifiche e la conversazione di Claude per gestire lo stato della sessione.

Claude Code traccia automaticamente le modifiche ai file di Claude mentre lavori, permettendoti di annullare rapidamente le modifiche e tornare a stati precedenti se qualcosa non va come previsto.

Come funziona il checkpointing

Mentre lavori con Claude, il checkpointing cattura automaticamente lo stato del tuo codice prima di ogni prompt dell'utente.

Tracciamento automatico

Claude Code traccia tutti i cambiamenti effettuati dai suoi strumenti di modifica dei file:

  • Ogni prompt dell'utente crea un nuovo checkpoint
  • Claude Code mantiene snapshot dei file per i 100 checkpoint più recenti in una sessione. L'eliminazione di un checkpoint più vecchio cancella i file snapshot che nessun checkpoint rimanente referenzia, ad eccezione del primo snapshot di ogni file, che l'estensione VS Code utilizza come baseline per i suoi diff di sessione.
  • Claude Code salva i checkpoint con la conversazione, quindi puoi comunque eseguire /rewind dopo aver ripreso una sessione
  • Claude Code elimina gli snapshot dei file di una sessione nella retention sweep, per impostazione predefinita circa 30 giorni dopo l'ultimo salvataggio della sessione. Il riavvolgimento a un checkpoint i cui snapshot sono scomparsi può fallire con No files were restored. Per mantenere gli snapshot più a lungo, imposta cleanupPeriodDays.

Riavvolgi e riassumi

Esegui /rewind, oppure premi Esc due volte quando il campo di input del prompt è vuoto, per aprire il menu di riavvolgimento.

Il menu di riavvolgimento elenca ogni prompt che hai inviato durante la sessione. Seleziona il punto su cui desideri agire, quindi scegli un'azione:

  • Ripristina codice e conversazione: ripristina sia il codice che la conversazione a quel punto
  • Ripristina conversazione: riavvolgi al messaggio mantenendo il codice attuale
  • Ripristina codice: ripristina le modifiche ai file mantenendo la conversazione
  • Riassumi da qui: comprimi la conversazione da questo punto in avanti in un riassunto, liberando spazio nella context window
  • Riassumi fino a qui: comprimi la conversazione prima di questo punto in un riassunto, mantenendo i messaggi successivi intatti
  • Non importa: torna all'elenco dei messaggi senza apportare modifiche

Le due opzioni di ripristino del codice appaiono solo quando il checkpoint selezionato ha tracciato modifiche ai file da ripristinare. Se nessuna modifica ai file è stata acquisita dopo quel punto, il menu offre solo Ripristina conversazione, le opzioni di riassunto e Non importa.

Dopo aver ripristinato la conversazione o aver scelto Riassumi da qui, il prompt originale dal messaggio selezionato viene ripristinato nel campo di input in modo che tu possa reinviarlo o modificarlo.

Scegliendo Riassumi fino a qui ti lascia alla fine della conversazione con l'input vuoto. Con entrambe le opzioni di riassunto, un marcatore Summarized conversation appare nella conversazione dove i messaggi compressi erano.

Riavvolgi oltre una conversazione cancellata

Se hai eseguito /clear in precedenza nello stesso processo Claude Code, il menu di riavvolgimento mostra una voce aggiuntiva in cima all'elenco etichettata /resume <session-id> (previous session). Selezionala per riprendere la conversazione che era attiva prima che /clear venisse eseguito. La voce è disponibile fino a quando non esci da Claude Code o riprendi una sessione diversa, e richiede Claude Code v2.1.191 o versione successiva. Nelle versioni precedenti, esegui /resume e scegli la sessione precedente dall'elenco.

Guida un riassunto

Il riassunto non modifica i file su disco, e i messaggi originali rimangono nella trascrizione della sessione, quindi Claude può comunque fare riferimento ai dettagli. Per guidare su cosa si concentra il riassunto, evidenzia un'opzione Summarize con i tasti freccia e digita le istruzioni dove la riga legge add context (optional), quindi premi Enter. Selezionando l'opzione con il suo tasto numerico si riassume immediatamente senza istruzioni.

Casi d'uso comuni

I checkpoint sono particolarmente utili quando:

  • Esplorare alternative: prova diversi approcci di implementazione senza perdere il tuo punto di partenza
  • Recuperare da errori: annulla rapidamente le modifiche che hanno introdotto bug o rotto la funzionalità
  • Iterare sulle funzionalità: sperimenta variazioni sapendo che puoi tornare a stati funzionanti
  • Liberare spazio di contesto: riassumi una sessione di debug dettagliata dal punto intermedio in avanti, mantenendo le tue istruzioni iniziali intatte

Limitazioni

Le modifiche dei comandi Bash non vengono tracciate

Il checkpointing non traccia i file modificati dai comandi bash. Ad esempio, se Claude Code esegue:

rm file.txt
mv old.txt new.txt
cp source.txt dest.txt

Queste modifiche ai file non possono essere annullate tramite riavvolgimento. Solo le modifiche dirette ai file effettuate attraverso gli strumenti di modifica dei file di Claude vengono tracciate.

Le modifiche dei subagent non vengono ripristinate

Un subagent effettua modifiche con gli strumenti di modifica dei file di Claude, ma Claude Code di solito non acquisisce queste modifiche nei checkpoint della tua sessione. Se il rewind ripristina le modifiche dipende da come viene eseguito il subagent:

  • Skill forked in foreground: una skill con context: fork che viene eseguita in foreground modifica il tuo working tree durante il tuo turno, quindi il rewind ripristina le sue modifiche come al solito. Imposta background: false per eseguire un fork in foreground; alcune situazioni, elencate nella pagina delle skills, lo eseguono lì indipendentemente dall'impostazione.
  • Qualsiasi altro subagent: il rewind non ripristina le modifiche. Utilizza git per ripristinarle. Questo include una skill forked che viene eseguita in background, l'impostazione predefinita, e un'esecuzione di /code-review --fix in background.

Le modifiche esterne non vengono tracciate

Il checkpointing traccia solo i file che sono stati modificati nella sessione corrente. Le modifiche manuali che effettui ai file al di fuori di Claude Code e le modifiche da altre sessioni concorrenti normalmente non vengono acquisite, a meno che non modifichino gli stessi file della sessione corrente.

I percorsi symlink e hard-link non vengono ripristinati

Il checkpointing non riavvolge i file symlink o hard-link. Quando scegli Restore code o Restore code and conversation dal menu /rewind, Claude Code salta qualsiasi percorso tracciato che è un symlink o hard link e mostra un avviso Restored the code, but skipped N files. I file saltati mantengono i loro contenuti attuali. Per annullare le modifiche della sessione a uno di essi, chiedi a Claude di invertire la modifica o modifica il file tu stesso. I file di configurazione che un gestore dotfile symlink nel tuo progetto e i file che pnpm hard-link nel posto rientrano entrambi in questa categoria.

Per vedere quali percorsi un ripristino salta, attiva la registrazione di debug con /debug prima di ripristinare: il log di debug in ~/.claude/debug/<session-id>.txt nomina ogni percorso saltato. Per ogni motivo di salto e i passaggi di recupero, vedi la voce skipped-files nel riferimento degli errori.

Non è un sostituto del controllo della versione

I checkpoint sono progettati per il recupero rapido a livello di sessione. Per la cronologia permanente della versione e la collaborazione, continua a utilizzare il controllo della versione, come Git, per commit, rami e cronologia a lungo termine.

Vedi anche