Tutorial 10: Checkpoints — AI's Undo Button

Tutorial 10: Checkpoints — O Botão de Desfazer da IA

Lembra daquela sensação horrível quando você percebe que acabou de deletar algo importante? Talvez um arquivo em que você passou horas trabalhando, ou uma mudança de configuração que quebrou tudo. No mundo real, não existe Ctrl+Z para o seu sistema de arquivos. Mas no Hermes Agent existe — e se chama checkpoints.

Pense nos checkpoints como pontos de salvamento em um videogame. Antes do seu agente de IA fazer algo arriscado — como sobrescrever um arquivo ou rodar um comando destrutivo — ele pode tirar um snapshot rápido do seu projeto. Se algo der errado, você pode voltar para aquele snapshot com um único comando. É como ter um botão de desfazer para o seu projeto inteiro.

Ativando a Rede de Segurança

Vamos ser honestos: checkpoints são opt-in no Hermes v2. A maioria dos usuários nunca precisa deles, e o armazenamento pode crescer com o tempo. Mas se você está trabalhando em algo importante, eles são um salva-vidas.

Você tem duas formas de ativá-los:

Por sessão (apenas para um chat):

hermes chat --checkpoints

Globalmente (em ~/.hermes/config.yaml):

checkpoints:
  enabled: true

Só isso. Uma vez ativado, o Hermes automaticamente tira snapshots do seu projeto antes de qualquer ação destrutiva.

O Que Dispara um Checkpoint?

O Hermes é inteligente sobre quando tirar snapshots. Ele observa:

• Operações de arquivo — como write_file e patch
• Comandos de terminal destrutivos — como rm, mv, sed -i, truncate, e até git reset ou git clean

A melhor parte? Ele cria no máximo um checkpoint por diretório por turno, então suas sessões longas não vão gerar centenas de snapshots.

Voltando no Tempo: Os Comandos de Barra

Quando você está em uma sessão de chat, /rollback é seu melhor amigo:

Comando	O que faz
/rollback	Mostra todos os checkpoints com estatísticas de mudanças
/rollback <N>	Restaura para o checkpoint N, mantendo suas edições manuais
/rollback <N> --all	Restauração completa — sobrescreve também suas edições manuais
/rollback diff <N>	Pré-visualiza as mudanças entre o checkpoint N e agora
/rollback <N> <file>	Restaura apenas um arquivo do checkpoint N

O /rollback <N> padrão é esperto — ele mantém qualquer alteração que você fez manualmente, desfazendo apenas o que o agente fez. Se você quiser uma limpeza completa, use --all.

Gerenciando o Armazenamento pelo Terminal

Fora do chat, você tem comandos CLI para inspecionar e gerenciar seus checkpoints:

hermes checkpoints              # Mostra tamanho, projetos, detalhamento
hermes checkpoints status       # Igual ao acima
hermes checkpoints list         # Atalho para status
hermes checkpoints prune        # Limpa órfãos e dados obsoletos
hermes checkpoints clear        # Deleta tudo (pede confirmação)
hermes checkpoints clear-legacy # Remove arquivos antigos de migração v1

Como Funciona por Baixo dos Panos

Você deve estar se perguntando: “Isso mexe com meu repositório git real?” Não. O Hermes mantém um “armazenamento sombra” separado em ~/.hermes/checkpoints/store/. O .git real do seu projeto nunca é tocado.

Todos os seus projetos compartilham esse único armazenamento, e como o git é endereçado por conteúdo, arquivos que aparecem em vários projetos são armazenados apenas uma vez. É surpreendentemente eficiente.

Ajustando as Configurações

Você pode controlar quanto armazenamento os checkpoints usam:

checkpoints:
  enabled: true
  max_snapshots: 20           # Máximo de checkpoints por projeto
  max_total_size_mb: 500      # Limite máximo do tamanho total do armazenamento
  max_file_size_mb: 10        # Ignora arquivos maiores que isso
  auto_prune: true            # Limpeza automática de entradas antigas
  retention_days: 7           # Mantém entradas por 7 dias
  min_interval_hours: 24      # Limpeza no máximo uma vez por dia

O recurso de limpeza automática é inteligente — ele remove entradas antigas na inicialização, mas nunca deleta entradas “órfãs” (projetos cujas pastas não são encontradas). Isso porque uma pasta ausente pode simplesmente significar que um drive externo ainda não foi montado. Para limpeza de órfãos, você precisará rodar hermes checkpoints prune manualmente.

O Botão de Desfazer do Seu Projeto

Os checkpoints te dão a confiança para deixar seu agente de IA trabalhar livremente, sabendo que você sempre pode voltar no tempo. Seja para refatorar código, experimentar configurações, ou só pela paz de espírito, vale a pena ativar.

Experimente na sua próxima sessão com hermes chat --checkpoints. Talvez você nunca precise voltar atrás — mas se precisar, vai ficar feliz que ele está lá.

---