Checkpoints e Rewind
- Entender o que um checkpoint captura — e o que ele silenciosamente não captura
- Abrir o menu de rewind de duas formas e escolher a ação de restauração certa todas as vezes
- Distinguir 'restaurar' (desfazer o estado) de 'resumir' (comprimir o contexto)
- Saber exatamente por que os checkpoints complementam o Git, mas nunca o substituem
A grande ideia
Quando você solta o Claude em uma mudança ambiciosa e de grande escala, a pergunta mais assustadora é "e se der errado três edições adiante?" O checkpointing é a resposta: o Claude Code tira automaticamente um snapshot do seu código antes de cada turno que você inicia, para que você possa voltar a qualquer estado anterior em vez de desembaraçar à mão uma refatoração pela metade.
Pense nele como um desfazer local para a sessão inteira — uma rede de segurança que permite dizer "sim, tente a abordagem ousada" sem medo.
Como os checkpoints são criados
Você não cria checkpoints — eles acontecem automaticamente.
- Cada prompt que inicia um turno captura o estado do seu código antes de as ferramentas de edição de arquivos do Claude rodarem. Sem comando, sem configuração, sem cerimônia.
- O Claude Code mantém snapshots de arquivos para os 100 checkpoints mais recentes de uma sessão. Os mais antigos são descartados, então uma sessão muito longa não pode ser revertida até o começo.
- Os checkpoints são salvos junto com a conversa, então você ainda pode executar /rewind depois de retomar uma sessão, não apenas na sessão ativa.
- Os snapshots de arquivos de uma sessão são apagados na varredura de retenção, por padrão cerca de 30 dias depois que a sessão salvou um snapshot pela última vez. Voltar a um checkpoint cujos snapshots já se foram falha com 'No files were restored' — aumente cleanupPeriodDays para mantê-los por mais tempo.
Abrindo o menu de rewind
Há duas formas de entrar:
- Digite o comando de barra no prompt. Sempre funciona. /checkpoint e /undo são aliases do mesmo comando, então use o nome que lhe vier à cabeça.
- Esc duplo abre o menu de rewind quando a caixa de prompt está vazia. Se houver texto nela, o Esc duplo apaga esse texto (o texto apagado vai para o histórico de entrada, então pressione Seta para cima para recuperá-lo depois).
Abrir o menu de rewind
/rewind
- Os nomes dos aliases são mais amigáveis do que literais: /checkpoint não tira um snapshot sob demanda (os snapshots são automáticos), e /undo não desfaz sozinho a última edição. Os três nomes abrem o mesmo menu, no qual você ainda escolhe o ponto e a ação.
O menu lista todos os prompts que você enviou nesta sessão. Escolha o ponto em que quer agir e depois uma ação.
Restaurar vs. resumir: a distinção-chave
É aqui que as pessoas se confundem. O menu oferece dois tipos de ação:
- As ações de restaurar alteram o estado em disco e/ou na conversa — elas desfazem.
- As ações de resumir nunca tocam nos seus arquivos — elas comprimem a conversa para liberar espaço na janela de contexto.
- Restaurar = desfazer (reverte o código, a conversa ou ambos). Resumir = comprimir o contexto (os arquivos em disco ficam intactos).
- Recorra a restaurar quando uma edição quebrou algo. Recorra a resumir quando a sessão está inchada mas o código está bom.
As ações de restaurar
- Reverte tanto os arquivos quanto o histórico do chat até o ponto selecionado — um 'voltar no tempo' limpo até aquele momento.
- Volta o chat até aquela mensagem, mas mantém o código atual. Útil para refazer uma pergunta sem perder edições que você quer manter.
- Reverte as mudanças nos arquivos, mas mantém a conversa. Desfaz as edições e preserva a discussão sobre elas.
As duas opções de restaurar código só aparecem quando o checkpoint selecionado realmente tem mudanças de arquivo rastreadas para reverter. Se nenhuma edição de arquivo foi capturada depois desse ponto, o menu oferece apenas Restaurar conversa, as duas opções de resumir e Never mind (que volta à lista de mensagens sem mudar nada).
Depois de restaurar a conversa (ou de escolher "Summarize from here"), o prompt original da mensagem selecionada volta para o campo de entrada, para você reenviá-lo ou editá-lo.
As ações de resumir
Ambas comprimem parte da conversa em um resumo gerado por IA — como um /compact direcionado, em que você escolhe qual lado da mensagem selecionada comprimir.
- As mensagens ANTES da mensagem selecionada permanecem intactas. A mensagem selecionada e tudo o que vem depois viram um resumo. Use para descartar uma discussão paralela mantendo o contexto inicial em todos os detalhes.
- As mensagens ANTES da mensagem selecionada viram um resumo; a mensagem selecionada e tudo o que vem depois permanecem intactos. Você continua no fim da conversa. Use para comprimir a conversa inicial de preparação mantendo o trabalho recente literal.
As mensagens originais continuam na transcrição da sessão de qualquer forma, então o Claude ainda pode consultar os detalhes, e um marcador Summarized conversation aparece onde ficavam as mensagens comprimidas. Para orientar o foco do resumo, destaque uma opção Summarize com as setas e digite instruções onde a linha diz add context (optional), depois pressione Enter — escolher a opção pela tecla numérica resume imediatamente, sem instruções.
Para o fluxo completo, veja Gerenciamento de contexto — as ações de resumir do /rewind são um bisturi, enquanto o /compact é um pincel largo.
- Resumir mantém você na mesma sessão. Para criar uma ramificação e tentar outra abordagem deixando a sessão original intacta, use /branch ou claude --continue --fork-session.
Voltando além de um /clear
Se você executou /clear antes, no mesmo processo do Claude Code, o menu de rewind mostra uma entrada extra no topo: /resume <session-id> (previous session). Selecione-a para voltar à conversa que estava ativa antes do /clear.
Onde os checkpoints terminam — os limites que machucam
Os checkpoints parecem mágicos até deixarem de ser. Estas lacunas importam:
- O rastreamento é por arquivo, e um arquivo só entra nele quando o Claude o edita com suas ferramentas de edição de arquivos. Depois que isso acontece, o /rewind também desfaz o que comandos Bash fazem com esse mesmo arquivo em seguida — um formatador ou gerador que reescreve um arquivo já editado pode ser revertido. Um arquivo que só o Bash tocou não é rastreado e fica como está, então um arquivo apagado com rm que o Claude nunca editou precisa do Git. O menu reflete isso: sob cada prompt, ele conta as mudanças em arquivos que o Claude já havia editado, seja qual for a causa.
- Um subagent edita com as mesmas ferramentas de arquivo, mas sua sessão normalmente não captura essas edições. A exceção é uma skill bifurcada em primeiro plano (context: fork com background: false), que edita durante o seu próprio turno e é revertida normalmente. Com qualquer outro subagent — incluindo uma skill bifurcada em segundo plano, que é o padrão, e uma execução de /code-review --fix em segundo plano — o rewind restaura apenas os arquivos que o Claude já havia editado na sua conversa; as edições do subagent em outros arquivos permanecem, então desfaça-as com o Git. Veja /docs/claude-code/subagents.
- Edições manuais feitas fora do Claude Code e edições de outras sessões concorrentes normalmente não são capturadas — a menos que toquem os mesmos arquivos que a sessão atual editou.
- Uma mensagem que você enfileira enquanto o Claude trabalha e que o alcança dentro do turno em andamento entra nesse turno em vez de iniciar um novo, então não recebe um checkpoint próprio — o menu de rewind a marca como 'No code restore'. Para desfazer o que veio depois dela, volte ao prompt que iniciou o turno, o que reverte o turno inteiro, inclusive o trabalho feito antes de a sua mensagem chegar. Selecionar a própria mensagem marcada ainda oferece Restaurar conversa, deixando os arquivos como estão.
- O Claude Code salva a conversa rebobinada junto com o próximo prompt que você enviar — então, se você sair antes de enviar um, as mensagens rebobinadas voltam quando você retomar a sessão. Envie um prompt ao Claude antes de sair para que a restauração valha; para descartar de novo mais tarde as mensagens que voltaram, execute /rewind, selecione o mesmo prompt e escolha Restore conversation. Os arquivos que você restaurou ficam como o rewind os deixou em ambos os casos, então isso afeta apenas a conversa.
- A restauração ignora qualquer caminho rastreado que seja um symlink ou hard link e avisa 'Restored the code, but skipped N files'; esses arquivos mantêm o conteúdo atual. Symlinks de gerenciadores de dotfiles e hard links do pnpm caem nesse caso. Execute /debug antes de restaurar para que os caminhos ignorados sejam nomeados no log de debug.
- Os checkpoints são uma recuperação local e rápida. Não são commits, não são branches e não podem ser compartilhados com a sua equipe.
Checkpoints vs. Git: use os dois
Eles resolvem problemas diferentes, então combine-os.
Checkpoints (/rewind) | Git | |
|---|---|---|
| Escopo | Uma sessão | Histórico inteiro do projeto |
| Granularidade | Por prompt que inicia um turno, automática | Por commit, deliberada |
| Rastreia mudanças feitas via bash? | Só em arquivos que o Claude já editou | Sim (depois de staged/commitadas) |
| Duração | Últimos 100 checkpoints, varridos ~30 dias após a sessão | Permanente |
| Compartilhável / colaborativo | Não | Sim |
| Modelo mental | "Desfazer local" | "Histórico permanente" |
- Faça commit dos estados que funcionam com o Git antes de uma execução arriscada e de grande escala — esse é o seu piso durável.
- Use /rewind para uma recuperação rápida dentro da sessão entre commits, sem poluir o histórico do Git.
- Apoie-se no Git para arquivos que o Claude nunca edita diretamente — aqueles que só um bash destrutivo (rm/mv) ou um subagent em segundo plano toca. O rewind só cobre um arquivo depois que o Claude o editou com suas próprias ferramentas de arquivo.
Quando recorrer a ele
- Tente uma implementação ousada e, se não gostar, restaure código e conversa até o ponto de bifurcação e tente outra.
- Uma edição introduziu um bug três prompts atrás? Restaure o código para logo antes dela em vez de depurar os destroços.
- Experimente variações sabendo sempre que um estado funcional conhecido está a um /rewind de distância.
- Um desvio verboso de depuração consumiu sua janela de contexto? Resuma do ponto intermediário em diante e mantenha suas instruções originais em todos os detalhes.
Teste-se
0/3- Os checkpoints são snapshots automáticos tirados antes de cada prompt que inicia um turno — um desfazer local para a sessão. Os últimos 100 são mantidos e depois varridos ~30 dias após a sessão.
- Abra o menu de rewind com /rewind (aliases: /checkpoint, /undo) ou Esc duplo em uma entrada vazia; ele lista todos os prompts que você enviou.
- As ações de restaurar desfazem o estado (código, conversa ou ambos); as ações de resumir comprimem o contexto e nunca tocam nos arquivos.
- O rastreamento é por arquivo e começa quando o Claude o edita com suas ferramentas de arquivo — depois disso, até as mudanças via Bash nesse arquivo são revertidas. Arquivos que o Claude nunca editou (só bash, externos, concorrentes, a maioria dos de subagents) não são rastreados, e caminhos com symlink ou hard link são ignorados no restore.
- Os checkpoints complementam o Git, não o substituem: pense em 'desfazer local' vs. 'histórico permanente e compartilhável'.
Próximo
- Gerenciamento de contexto —
/compact,/cleare como o resumir se encaixa no quadro geral - Plan Mode — investigue e aprove um plano antes de as edições rodarem, para você precisar voltar menos vezes
- Permissões — a outra metade de executar tarefas ambiciosas com segurança