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 os checkpoints funcionam

Enquanto você trabalha com o 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

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

• Cada prompt que você envia e que inicia um turno cria um novo checkpoint
• O Claude Code mantém snapshots de arquivos para os 100 checkpoints mais recentes em uma sessão. Descartar um checkpoint mais antigo exclui os arquivos de snapshot que nenhum checkpoint restante referencia, exceto o primeiro snapshot de cada arquivo, que a extensão do VS Code usa como base para seus diffs da sessão.
• O Claude Code salva os checkpoints junto com a conversa, então você ainda pode executar /rewind depois de retomar uma sessão
• O Claude Code exclui os snapshots de arquivos de uma sessão na limpeza de retenção, por padrão cerca de 30 dias depois que a sessão salvou o último. Retroceder para um checkpoint cujos snapshots não existem mais pode falhar com No files were restored. Para manter os snapshots por mais tempo, defina cleanupPeriodDays.

Retroceder e resumir

Execute /rewind, ou pressione Esc duas vezes quando a entrada de prompt estiver vazia, para abrir o menu de retrocesso.

[!NOTE]

Se a entrada de prompt contiver texto, pressionar Esc duas vezes a limpa em vez de abrir o menu. O texto limpo é salvo no seu histórico de entrada, então pressione Up para recuperá-lo depois de terminar no menu de retrocesso.

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

• Restore code and conversation: reverte tanto o código quanto a conversa para aquele ponto
• Restore conversation: retrocede até aquela mensagem mantendo o código atual
• Restore code: reverte as alterações de arquivos mantendo a conversa
• Summarize from here: comprime a conversa a partir deste ponto em um resumo, liberando espaço na janela de contexto
• Summarize up to here: comprime a conversa anterior a este ponto em um resumo, mantendo as mensagens posteriores intactas
• Never mind: 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 arquivos rastreadas para reverter. Se nenhuma edição de arquivo foi capturada após aquele ponto, o menu oferece apenas Restore conversation, as opções de resumo e Never mind.

Depois de restaurar a conversa ou escolher Summarize from here, o prompt original da mensagem selecionada é restaurado no campo de entrada para que você possa reenviá-lo ou editá-lo.

Escolher Summarize up to here deixa você no final da conversa com a entrada vazia. Com qualquer uma das opções de resumo, um marcador Summarized conversation aparece na conversa onde estavam as mensagens comprimidas.

Mensagens retrocedidas 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 e, em seguida, Restore conversation. Antes de sair, envie um prompt ao Claude, porque o Claude Code salva a conversa retrocedida junto com esse prompt. Os arquivos que você restaurou permanecem como o retrocesso os deixou.

Retroceder além de uma conversa limpa

Se você executou /clear anteriormente no mesmo processo do Claude Code, o menu de retrocesso 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 fica disponível até você sair do Claude Code ou retomar uma sessão diferente.

Orientar um resumo

Resumir não altera arquivos no disco, e as mensagens originais permanecem na transcrição da sessão, então o Claude ainda pode consultar os detalhes. Para orientar o foco do resumo, destaque uma opção Summarize com as teclas de seta e digite instruções onde a linha mostra add context (optional) e, em seguida, pressione Enter. Selecionar a opção com sua tecla numérica resume imediatamente, sem instruções.

[!NOTE]

Resumir mantém você na mesma sessão e comprime o contexto, como um /compact direcionado. Para criar um branch e tentar uma abordagem diferente preservando 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