Skip to main content
Il checkpointing dei file traccia le modifiche ai file effettuate tramite gli strumenti Write, Edit e NotebookEdit durante una sessione dell’agente, consentendoti di ripristinare i file a qualsiasi stato precedente. Per vedere un esempio interattivo di ripristino di un file, vai all’esempio interattivo.
Solo le modifiche effettuate tramite gli strumenti Write, Edit e NotebookEdit vengono tracciate. Le modifiche effettuate tramite comandi Bash (come echo > file.txt o sed -i) non vengono acquisite dal sistema di checkpoint, e nemmeno le modifiche che un subagent applica, ad eccezione di una skill con context: fork che viene eseguita in primo piano.

Come funziona il checkpointing

Quando abiliti il checkpointing dei file, l’SDK crea backup dei file prima di modificarli tramite gli strumenti Write, Edit o NotebookEdit. I messaggi dell’utente nel flusso di risposta includono un UUID di checkpoint che puoi utilizzare come punto di ripristino.
Il ripristino dei file ripristina i file su disco a uno stato precedente. Non ripristina la conversazione stessa. La cronologia della conversazione e il contesto rimangono intatti dopo la chiamata a rewindFiles() (TypeScript) o rewind_files() (Python).
Quando ripristini a un checkpoint, Claude Code elimina i file che ha creato e ripristina i file che ha modificato al loro contenuto in quel momento. Claude Code salta un percorso tracciato che è un symlink, hard link o altro file non regolare. Salta anche un file tracciato il cui directory padre non si risolve più nella sua posizione al momento del checkpoint, o il cui backup non può leggere in modo sicuro. RewindFilesResult conta ogni percorso saltato nel suo campo skippedLinks. Il salto richiede Claude Code v2.1.216 o successivo; prima di v2.1.216, un ripristino scriveva ed eliminava attraverso i link nei percorsi tracciati.

Implementare il checkpointing

Per utilizzare il checkpointing dei file, abilitalo nelle tue opzioni, acquisisci gli UUID di checkpoint dal flusso di risposta, quindi chiama rewindFiles() (TypeScript) o rewind_files() (Python) quando hai bisogno di ripristinare. Gli esempi in questa sezione utilizzano il prompt “Refactor the authentication module”. Eseguili in un progetto che contiene un modulo di autenticazione, oppure modifica il prompt per nominare file che esistono nel tuo progetto, in modo da poter osservare i file cambiare e vedere il ripristino ripristinarli. Questo esempio abilita il checkpointing, acquisisce l’UUID di checkpoint e l’ID di sessione dal flusso di risposta, quindi riprende la sessione in seguito per ripristinare i file. I commenti numerati dell’esempio corrispondono ai passaggi che seguono.
1

Abilita il checkpointing

Configura le opzioni dell’SDK per abilitare il checkpointing e ricevere gli UUID di checkpoint:L’esempio principale in Implementare il checkpointing imposta anche la modalità di autorizzazione su acceptEdits, che approva le modifiche ai file dell’agente senza un prompt. Per ulteriori informazioni, vedi Modalità di autorizzazione.
2

Acquisisci l'UUID di checkpoint e l'ID di sessione

Con l’opzione replay-user-messages impostata, ogni messaggio dell’utente nel flusso di risposta ha un UUID che funge da checkpoint.Per la maggior parte dei casi d’uso, acquisisci il primo UUID del messaggio dell’utente (message.uuid); il ripristino ad esso ripristina tutti i file al loro stato originale. Per archiviare più checkpoint e ripristinare a stati intermedi, vedi Più punti di ripristino.L’acquisizione dell’ID di sessione (message.session_id) è facoltativa; ne hai bisogno solo se vuoi ripristinare in seguito, dopo il completamento del flusso. Se stai chiamando rewindFiles() immediatamente mentre stai ancora elaborando i messaggi (come fa l’esempio in Checkpoint prima di operazioni rischiose), puoi saltare l’acquisizione dell’ID di sessione.
3

Ripristina i file

Per ripristinare dopo il completamento del flusso, riprendi la sessione con un prompt vuoto e chiama rewind_files() (Python) o rewindFiles() (TypeScript) con il tuo UUID di checkpoint. Abilita il checkpointing anche sulle opzioni della sessione ripresa e chiama il ripristino dall’interno del ciclo di risposta. Puoi anche ripristinare durante il flusso. Vedi Checkpoint prima di operazioni rischiose per quel modello.Se acquisisci l’ID di sessione e l’ID di checkpoint, puoi anche ripristinare dalla CLI. Questo comando richiede l’eseguibile claude, che proviene da installazione di Claude Code. L’SDK abilita il checkpointing per te, ma quando esegui claude -p direttamente devi impostare la variabile di ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING:
Il flag --rewind-files non appare nell’output di claude --help, ma la CLI lo accetta come mostrato. Quando il ripristino ha successo, il comando stampa Files rewound to state at message <checkpoint-uuid> e esce senza inviare un prompt.

Modelli comuni

Questi modelli mostrano diversi modi per acquisire e utilizzare gli UUID di checkpoint a seconda del tuo caso d’uso.

Checkpoint prima di operazioni rischiose

Questo modello mantiene solo l’UUID di checkpoint più recente, aggiornandolo prima di ogni turno dell’agente. Se qualcosa va storto durante l’elaborazione, puoi immediatamente ripristinare all’ultimo stato sicuro e uscire dal ciclo. Prima di eseguire questo esempio, sostituisci your_revert_condition (Python) o yourRevertCondition (TypeScript) con il tuo controllo personale, come il rilevamento di errori o un errore di convalida; il segnaposto non è definito nell’esempio.

Più punti di ripristino

Se Claude effettua modifiche su più turni, potresti voler ripristinare a un punto specifico piuttosto che all’inizio. Ad esempio, se Claude effettua il refactoring di un file nel turno uno e aggiunge test nel turno due, potresti voler mantenere il refactoring ma annullare i test. Questo modello archivia tutti gli UUID di checkpoint in un array con metadati. Dopo il completamento della sessione, puoi ripristinare a qualsiasi checkpoint precedente:

Prova

Questo esempio completo crea un piccolo file di utilità, fa aggiungere all’agente commenti di documentazione, ti mostra le modifiche, quindi ti chiede se vuoi ripristinare. Prima di iniziare, assicurati di avere Claude Agent SDK installato.
1

Crea un file di test

Crea un nuovo file chiamato utils.py (Python) o utils.ts (TypeScript) e incolla il seguente codice:
2

Esegui l'esempio interattivo

Crea un nuovo file chiamato try_checkpointing.py (Python) o try_checkpointing.ts (TypeScript) nella stessa directory del tuo file di utilità e incolla il seguente codice.Questo script chiede a Claude di aggiungere commenti doc al tuo file di utilità, quindi ti dà la possibilità di ripristinare e ripristinare l’originale.
3

Esegui l'esempio

Esegui lo script dalla stessa directory del tuo file di utilità.
Apri il tuo file di utilità (utils.py o utils.ts) nel tuo IDE o editor prima di eseguire lo script. Vedrai il file aggiornarsi in tempo reale mentre l’agente aggiunge commenti doc, quindi tornare all’originale quando scegli di ripristinare.
Vedrai l’agente aggiungere commenti doc, quindi un prompt che ti chiede se vuoi ripristinare. Se scegli sì, il file viene ripristinato al suo stato originale.

Limitazioni

Il checkpointing dei file ha le seguenti limitazioni:

Troubleshooting

Le opzioni di checkpointing non vengono riconosciute

Se enableFileCheckpointing o rewindFiles() non sono disponibili, potresti essere su una versione SDK più vecchia. Soluzione: Aggiorna alla versione SDK più recente:
  • Python: pip install --upgrade claude-agent-sdk
  • TypeScript: npm install @anthropic-ai/claude-agent-sdk@latest

I messaggi dell’utente non hanno UUID

Se message.uuid è undefined o mancante, non stai ricevendo gli UUID di checkpoint. Causa: L’opzione replay-user-messages non è impostata. Soluzione: Aggiungi extra_args={"replay-user-messages": None} (Python) o extraArgs: { 'replay-user-messages': null } (TypeScript) alle tue opzioni.

Errore “No file checkpoint found for this message”

Questo errore si verifica quando i dati di checkpoint non esistono per l’UUID del messaggio dell’utente specificato. Cause comuni:
  • Il checkpointing dei file non era abilitato sulla sessione originale (enable_file_checkpointing o enableFileCheckpointing non era impostato su true)
  • La sessione non è stata completata correttamente prima di tentare di riprendere e ripristinare
Soluzione: Assicurati che enable_file_checkpointing=True (Python) o enableFileCheckpointing: true (TypeScript) fosse impostato sulla sessione originale, quindi utilizza il modello mostrato negli esempi: acquisisci il primo UUID del messaggio dell’utente, completa la sessione completamente, quindi riprendi con un prompt vuoto e chiama rewindFiles() una volta.

Errore “File rewinding is not enabled”

Questo errore si verifica quando tenti un rewind non interattivo senza checkpointing abilitato: eseguire il bare claude -p con --rewind-files, o eseguire una sessione SDK, inclusa una ripresa, le cui opzioni non abilitano il checkpointing. L’SDK imposta la variabile di ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING internamente solo quando enable_file_checkpointing (Python) o enableFileCheckpointing (TypeScript) è abilitato sulla sessione che esegue il rewind; il bare CLI non la imposta mai. Soluzione: Per il bare CLI, imposta la variabile di ambiente quando esegui il comando:
Per l’SDK, imposta enable_file_checkpointing=True (Python) o enableFileCheckpointing: true (TypeScript) sulla sessione ripresa, come fanno gli esempi su questa pagina.

Errore “ProcessTransport is not ready for writing”

Questo errore si verifica quando chiami rewindFiles() o rewind_files() dopo aver terminato l’iterazione attraverso la risposta. La connessione al processo CLI si chiude quando il ciclo si completa. Soluzione: Riprendi la sessione con un prompt vuoto, quindi chiama rewind sulla nuova query. L’esempio principale sotto Implement checkpointing mostra la chiamata resume-and-rewind in entrambi i linguaggi, al commento contrassegnato Step 3.

Passaggi successivi

  • Sessions: scopri come riprendere le sessioni, che è obbligatorio per il ripristino dopo il completamento del flusso. Copre gli ID di sessione, la ripresa delle conversazioni e il forking delle sessioni.
  • Permissions: configura quali strumenti Claude può utilizzare e come vengono approvate le modifiche ai file. Utile se vuoi più controllo su quando avvengono le modifiche.
  • TypeScript SDK reference: riferimento API completo incluse tutte le opzioni per query() e il metodo rewindFiles().
  • Python SDK reference: riferimento API completo incluse tutte le opzioni per ClaudeAgentOptions e il metodo rewind_files().