Checkpointing

Rastreie, reverta e resuma as edições e conversas do Claude para gerenciar o estado da sessão.

Claude Code rastreia automaticamente as edições de arquivo do Claude conforme você trabalha, permitindo que você desfaça rapidamente as alterações e reverta para estados anteriores se algo sair do caminho.

Como o checkpointing funciona

Conforme você trabalha com Claude, o checkpointing captura automaticamente o estado do seu código antes de cada prompt que você envia e que inicia um turno.

Rastreamento automático

Claude Code rastreia todas as alterações feitas por suas ferramentas de edição de arquivo:

• Cada prompt que você envia e que inicia um turno cria um novo checkpoint
• Claude Code mantém snapshots de arquivo para os 100 checkpoints mais recentes em uma sessão. Descartar um checkpoint mais antigo deleta os arquivos de snapshot que nenhum checkpoint restante referencia, exceto o primeiro snapshot de cada arquivo, que a extensão VS Code usa como baseline para seus diffs de sessão.
• Claude Code salva checkpoints com a conversa, para que você ainda possa executar /rewind após retomar uma sessão
• Claude Code deleta os snapshots de arquivo de uma sessão na varredura de retenção, por padrão cerca de 30 dias após a sessão salvar um pela última vez. Fazer rewind para um checkpoint cujos snapshots desapareceram pode falhar com No files were restored. Para manter snapshots por mais tempo, defina cleanupPeriodDays.

Rewind e resumo

Execute /rewind, ou pressione Esc duas vezes quando o campo de entrada de prompt estiver vazio, para abrir o menu de rewind.

[!NOTE]

Se o campo de entrada de prompt contiver texto, duplo Esc o limpa em vez de abrir o menu. O texto limpo é salvo no seu histórico de entrada, então pressione Up para recuperá-lo após terminar no menu de rewind.

O menu de rewind lista os prompts que você enviou durante a sessão. Selecione o ponto em que deseja agir e escolha uma ação:

• Restaurar código e conversa: reverte tanto o código quanto a conversa para esse ponto
• Restaurar conversa: reverte para essa mensagem mantendo o código atual
• Restaurar código: reverte as alterações de arquivo mantendo a conversa
• Resumir a partir daqui: compacta a conversa a partir deste ponto em diante em um resumo, liberando espaço da context window
• Resumir até aqui: compacta a conversa antes deste ponto em um resumo, mantendo as mensagens posteriores intactas
• Nunca importa: retorna à lista de mensagens sem fazer alterações

As duas opções de restauração de código aparecem apenas quando o checkpoint selecionado tem alterações de arquivo rastreadas para reverter. Se nenhuma edição de arquivo foi capturada após esse ponto, o menu oferece apenas Restaurar conversa, as opções de resumo e Nunca importa.

Após restaurar a conversa ou escolher Resumir a partir daqui, o prompt original da mensagem selecionada é restaurado no campo de entrada para que você possa reenviá-lo ou editá-lo.

Escolher Resumir até aqui o deixa no final da conversa com a entrada vazia. Com qualquer opção de resumo, um marcador Conversa resumida aparece na conversa onde as mensagens compactadas estavam.

Mensagens revertidas podem retornar se você sair antes do seu próximo prompt

Para remover novamente as mensagens que retornaram, execute /rewind na sessão e selecione o mesmo prompt, depois Restaurar conversa. Antes de sair, envie um prompt para Claude, porque Claude Code salva a conversa revertida junto com esse prompt. Os arquivos que você restaurou permanecem como o rewind os deixou.

Rewind passado uma conversa limpa

Se você executou /clear anteriormente no mesmo processo Claude Code, o menu de rewind mostra uma entrada adicional no topo da lista rotulada /resume <session-id> (previous session). Selecione-a para retomar a conversa que estava ativa antes de /clear ser executado. A entrada está disponível até você sair do Claude Code ou retomar uma sessão diferente.

Guiar um resumo

Resumir não altera arquivos no disco, e as mensagens originais permanecem na transcrição da sessão, para que Claude ainda possa fazer referência aos detalhes. Para guiar o que o resumo se concentra, destaque uma opção Resumir com as teclas de seta e digite instruções onde a linha lê adicionar contexto (opcional), então pressione Enter. Selecionar a opção com sua tecla de número resume imediatamente sem instruções.

[!NOTE]

Resumir mantém você na mesma sessão e compacta o contexto, como um /compact direcionado. Para ramificar e tentar uma abordagem diferente enquanto preserva a sessão original intacta, use /branch ou claude --continue --fork-session em vez disso.

Casos de uso comuns

Os checkpoints são particularmente úteis quando:

• Explorando alternativas: tente diferentes abordagens de implementação sem perder seu ponto de partida
• Recuperando de erros: desfaça rapidamente as alterações que introduziram bugs ou quebraram a funcionalidade
• Iterando em recursos: experimente variações sabendo que você pode reverter para estados funcionais
• Liberando espaço de contexto: resuma uma sessão de depuração verbosa a partir do ponto médio em diante, mantendo suas instruções iniciais intactas

Limitações

Alterações de comando Bash não rastreadas

Depois que Claude edita um arquivo com suas ferramentas de edição de arquivo na sua conversa, /rewind desfaz as alterações que comandos Bash fazem nesse arquivo posteriormente. Um arquivo alterado apenas por comandos Bash não é rastreado e permanece como está. Para revertê-lo, use controle de versão, como Git.

Em cada prompt, o menu de rewind contabiliza as alterações em arquivos que Claude já havia editado, independentemente do que as fez. Um prompt em que um comando do shell alterou um desses arquivos também lista alterações de arquivo.

Edições de subagent não restauradas

Um subagent faz edições com as ferramentas de edição de arquivo do Claude, mas Claude Code geralmente não captura essas edições nos checkpoints da sua sessão. Se o rewind restaura essas edições depende de como o subagent é executado:

• Skill forked em foreground: uma skill com context: fork que é executada em foreground edita sua árvore de trabalho durante seu próprio turno, então o rewind restaura suas edições como de costume. Defina background: false para executar um fork em foreground; algumas situações, listadas na página de skills, o executam lá independentemente da configuração.
• Qualquer outro subagente: o rewind restaura apenas os arquivos que Claude já havia editado na sua conversa. As edições do subagente em outros arquivos permanecem, então use controle de versão, como Git, para revertê-las. Isso inclui uma skill forked que é executada em background, o padrão, e uma execução de /code-review --fix em background.

Alterações externas não rastreadas

O checkpointing rastreia apenas arquivos que foram editados na sessão atual. Alterações manuais que você faz em arquivos fora do Claude Code e edições de outras sessões simultâneas normalmente não são capturadas, a menos que aconteçam de modificar os mesmos arquivos da sessão atual.

Mensagens enviadas no meio do turno não checkpointed

No menu de rewind, uma mensagem que você digitou enquanto Claude ainda estava trabalhando pode ser marcada como No code restore. A mensagem marcada não tem um checkpoint próprio.

Para desfazer as edições de arquivo que Claude fez depois dessa mensagem, selecione o prompt que iniciou o turno e escolha Restore code ou Restore code and conversation. Isso reverte as edições de arquivo do Claude de todo o turno, incluindo as feitas antes de sua mensagem chegar.

Caminhos symlinked e hard-linked não restaurados

O checkpointing não faz rewind de arquivos symlinked ou hard-linked. Quando você seleciona Restore code ou Restore code and conversation no menu /rewind, Claude Code pula qualquer caminho rastreado que seja um symlink ou hard link e mostra um aviso Restored the code, but skipped N files. Os arquivos pulados mantêm seu conteúdo atual. Para desfazer as alterações da sessão em um deles, peça ao Claude para reverter a edição ou edite o arquivo você mesmo. Arquivos de configuração que um gerenciador de dotfiles symlinks em seu projeto e arquivos que pnpm hard-links em seu lugar ambos se enquadram nesta categoria.

Para ver quais caminhos um restore pula, ative o debug logging com /debug antes de restaurar: o debug log em ~/.claude/debug/<session-id>.txt nomeia cada caminho pulado. Para cada razão de skip e as etapas de recuperação, veja a entrada skipped-files na referência de erros.

Não é um substituto para controle de versão

Os checkpoints são projetados para recuperação rápida no nível da sessão. Para histórico de versão permanente e colaboração, continue usando controle de versão, como Git, para commits, branches e histórico de longo prazo.

Veja também

• Modo interativo - Atalhos de teclado e controles de sessão
• Comandos - Acessando checkpoints usando /rewind
• Referência CLI - Opções de linha de comando