Como o checkpointing funciona
Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. As mensagens do usuário no fluxo de resposta incluem um UUID de checkpoint que você pode usar como ponto de restauração.A reversão de arquivo restaura arquivos no disco para um estado anterior. Ela não reverte a conversa em si. O histórico de conversa e o contexto permanecem intactos após chamar
rewindFiles() (TypeScript) ou rewind_files() (Python).RewindFilesResult conta cada caminho ignorado em seu campo skippedLinks. Ignorar requer Claude Code v2.1.216 ou posterior; antes de v2.1.216, uma reversão escrevia e deletava através de links em caminhos rastreados.
Implementar checkpointing
Para usar checkpointing de arquivo, ative-o em suas opções, capture UUIDs de checkpoint do fluxo de resposta e, em seguida, chamerewindFiles() (TypeScript) ou rewind_files() (Python) quando precisar restaurar.
Os exemplos nesta seção usam o prompt “Refactor the authentication module”. Execute-os em um projeto que contenha um módulo de autenticação, ou altere o prompt para nomear arquivos que existem em seu projeto, para que você possa observar as alterações de arquivos e ver a reversão restaurá-los.
Este exemplo ativa checkpointing, captura o UUID de checkpoint e ID de sessão do fluxo de resposta e, em seguida, retoma a sessão mais tarde para reverter arquivos. Os comentários numerados do exemplo correspondem às etapas que se seguem.
1
Ativar checkpointing
Configure suas opções de SDK para ativar checkpointing e receber UUIDs de checkpoint:
O exemplo principal em Implementar checkpointing também define o modo de permissão como
acceptEdits, que aprova as edições de arquivo do agente sem um prompt. Para mais informações, consulte Modos de permissão.2
Capturar UUID de checkpoint e ID de sessão
Com a opção
replay-user-messages definida, cada mensagem do usuário no fluxo de resposta tem um UUID que serve como um checkpoint.Para a maioria dos casos de uso, capture o UUID da primeira mensagem do usuário (message.uuid); reverter para ele restaura todos os arquivos para seu estado original. Para armazenar múltiplos checkpoints e reverter para estados intermediários, veja Múltiplos pontos de restauração.Capturar o ID de sessão (message.session_id) é opcional; você só precisa dele se quiser reverter mais tarde, após o fluxo ser concluído. Se você estiver chamando rewindFiles() imediatamente enquanto ainda processa mensagens (como o exemplo em Checkpoint antes de operações arriscadas faz), você pode pular a captura do ID de sessão.3
Reverter arquivos
Para reverter após o fluxo ser concluído, retome a sessão com um prompt vazio e chame O sinalizador
rewind_files() (Python) ou rewindFiles() (TypeScript) com seu UUID de checkpoint. Ative checkpointing nas opções da sessão retomada também, e chame rewind de dentro do loop de resposta. Você também pode reverter durante o fluxo. Consulte Checkpoint antes de operações arriscadas para esse padrão.Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI. Este comando requer o executável claude, que vem de instalar Claude Code. O SDK ativa checkpointing para você, mas quando você executa claude -p diretamente, você deve definir a variável de ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING:--rewind-files não aparece na saída de claude --help, mas a CLI o aceita conforme mostrado. Quando a reversão é bem-sucedida, o comando imprime Files rewound to state at message <checkpoint-uuid> e sai sem enviar um prompt.Padrões comuns
Esses padrões mostram diferentes maneiras de capturar e usar UUIDs de checkpoint dependendo do seu caso de uso.Checkpoint antes de operações arriscadas
Este padrão mantém apenas o UUID de checkpoint mais recente, atualizando-o antes de cada turno do agente. Se algo der errado durante o processamento, você pode reverter imediatamente para o último estado seguro e sair do loop. Antes de executar este exemplo, substituayour_revert_condition (Python) ou yourRevertCondition (TypeScript) pela sua própria verificação, como detecção de erro ou falha de validação; o espaço reservado não está definido no exemplo.
Múltiplos pontos de restauração
Se Claude fizer alterações em múltiplos turnos, você pode querer reverter para um ponto específico em vez de voltar completamente. Por exemplo, se Claude refatorar um arquivo no turno um e adicionar testes no turno dois, você pode querer manter a refatoração mas desfazer os testes. Este padrão armazena todos os UUIDs de checkpoint em um array com metadados. Após a sessão ser concluída, você pode reverter para qualquer checkpoint anterior:Experimente
Este exemplo completo cria um pequeno arquivo utilitário, faz o agente adicionar comentários de documentação, mostra as alterações e pergunta se você quer reverter. Antes de começar, certifique-se de que você tem o Claude Agent SDK instalado.1
Criar um arquivo de teste
Crie um novo arquivo chamado
utils.py (Python) ou utils.ts (TypeScript) e cole o seguinte código:2
Executar o exemplo interativo
Crie um novo arquivo chamado
try_checkpointing.py (Python) ou try_checkpointing.ts (TypeScript) no mesmo diretório que seu arquivo utilitário e cole o seguinte código.Este script pede ao Claude para adicionar comentários de documentação ao seu arquivo utilitário e, em seguida, oferece a opção de reverter e restaurar o original.3
Executar o exemplo
Execute o script do mesmo diretório que seu arquivo utilitário.Você verá o agente adicionar comentários de documentação e, em seguida, um prompt perguntando se você quer reverter. Se você escolher sim, o arquivo é restaurado para seu estado original.
- Python
- TypeScript
Limitações
O checkpointing de arquivo tem as seguintes limitações:Troubleshooting
Opções de checkpointing não reconhecidas
SeenableFileCheckpointing ou rewindFiles() não estiver disponível, você pode estar em uma versão mais antiga do SDK.
Solução: Atualize para a versão mais recente do SDK:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
Mensagens do usuário não têm UUIDs
Semessage.uuid for undefined ou estiver faltando, você não está recebendo UUIDs de checkpoint.
Causa: A opção replay-user-messages não está definida.
Solução: Adicione extra_args={"replay-user-messages": None} (Python) ou extraArgs: { 'replay-user-messages': null } (TypeScript) às suas opções.
Erro “No file checkpoint found for this message”
Este erro ocorre quando os dados de checkpoint não existem para o UUID de mensagem do usuário especificado. Causas comuns:- O checkpointing de arquivo não foi ativado na sessão original (
enable_file_checkpointingouenableFileCheckpointingnão foi definido comotrue) - A sessão não foi concluída adequadamente antes de tentar retomar e reverter
enable_file_checkpointing=True (Python) ou enableFileCheckpointing: true (TypeScript) foi definido na sessão original, depois use o padrão mostrado nos exemplos: capture o UUID da primeira mensagem do usuário, conclua a sessão completamente e, em seguida, retome com um prompt vazio e chame rewindFiles() uma vez.
Erro “File rewinding is not enabled”
Este erro ocorre quando você tenta um rewind não interativo sem checkpointing ativado: executarclaude -p simples com --rewind-files, ou executar uma sessão SDK, incluindo uma retomada, cujas opções não ativam checkpointing. O SDK define a variável de ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING internamente apenas quando enable_file_checkpointing (Python) ou enableFileCheckpointing (TypeScript) está ativado na sessão que executa o rewind; a CLI simples nunca a define.
Solução: Para a CLI simples, defina a variável de ambiente ao executar o comando:
enable_file_checkpointing=True (Python) ou enableFileCheckpointing: true (TypeScript) na sessão retomada, como os exemplos nesta página fazem.
Erro “ProcessTransport is not ready for writing”
Este erro ocorre quando você chamarewindFiles() ou rewind_files() após ter terminado de iterar através da resposta. A conexão com o processo CLI fecha quando o loop é concluído.
Solução: Retome a sessão com um prompt vazio e, em seguida, chame rewind na nova query. O exemplo principal sob Implement checkpointing mostra a chamada de retomada e rewind em ambas as linguagens, no comentário marcado Etapa 3.
Próximos passos
- Sessions: aprenda como retomar sessões, o que é necessário para reverter após o fluxo ser concluído. Cobre IDs de sessão, retomada de conversas e bifurcação de sessão.
- Permissions: configure quais ferramentas Claude pode usar e como as modificações de arquivo são aprovadas. Útil se você quiser mais controle sobre quando as edições acontecem.
- TypeScript SDK reference: referência completa da API incluindo todas as opções para
query()e o métodorewindFiles(). - Python SDK reference: referência completa da API incluindo todas as opções para
ClaudeAgentOptionse o métodorewind_files().