Checkpoints e `/rollback` — Sua Rede de Segurança para Operações Destrutivas

Checkpoints e /rollback — Sua Rede de Segurança para Operações Destrutivas

Já assistiu um agente de IA rodar um comando como rm -rf ou sobrescrever um arquivo e pensou: “Eu realmente espero que ele saiba o que está fazendo”? Com o Hermes Agent v2, você agora tem uma rede de segurança adequada — checkpoints — que pode capturar um snapshot do seu projeto antes de operações arriscadas e restaurá-lo com um único comando.

A melhor parte? É completamente opt-in. A maioria dos usuários nunca toca no /rollback, e como o shadow-store pode crescer com o tempo, o padrão é desligado. Mas quando você precisa, é um salva-vidas.

Habilitando Checkpoints

Você pode habilitar checkpoints por sessão com uma flag simples:

hermes chat --checkpoints

Ou habilitá-los globalmente em ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Só isso. Uma vez habilitado, o Hermes automaticamente tira um snapshot do seu projeto antes que qualquer coisa destrutiva aconteça.

O Que Dispara um Checkpoint

O Hermes tira um checkpoint automaticamente antes de:

• Ferramentas de arquivo — write_file e patch
• Comandos de terminal destrutivos — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, redirecionamentos de saída (>), e git reset/clean/checkout

O agente cria no máximo um checkpoint por diretório por turno, então sessões longas não inundam de snapshots e não incham seu armazenamento.

Como Funciona por Baixo dos Panos

A mágica acontece através de um Gerenciador de Checkpoints interno que mantém um único repositório git shadow compartilhado em ~/.hermes/checkpoints/store/. O .git real do seu projeto nunca é tocado — tudo vive nesse store separado.

Aqui está o fluxo:

1. O Hermes detecta quando ferramentas estão prestes a modificar arquivos na sua árvore de trabalho.
2. Uma vez por turno de conversa (por diretório), ele resolve uma raiz de projeto razoável.
3. Ele inicializa ou reutiliza o shadow store compartilhado.
4. Ele faz stage dos arquivos em um índice por projeto, constrói uma árvore e faz commit para uma ref por projeto (refs/hermes/<project-hash>).

Como todos os projetos compartilham o mesmo store, o banco de dados de objetos endereçáveis por conteúdo do git deduplica entre projetos e entre turnos — então você não está desperdiçando espaço com conteúdo idêntico.

Usando /rollback na Sessão

Uma vez que você está em uma sessão com checkpoints habilitados, você tem vários comandos de barra à sua disposição:

Comando	Descrição
/rollback	Lista todos os checkpoints com estatísticas de mudanças
/rollback <N>	Restaura para o checkpoint N, mantendo suas edições manuais (também desfaz o último turno do chat)
/rollback <N> --all	Restauração completa — sobrescreve também suas edições manuais
/rollback diff <N>	Pré-visualiza o diff entre o checkpoint N e o estado atual
/rollback <N> <file>	Restaura um único arquivo do checkpoint N

Quando você executa /rollback, verá uma lista formatada assim:

📸 Checkpoints para /caminho/para/projeto:

  1. 4270a8c  2026-03-16 04:36  antes do patch  (1 arquivo, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  antes do write_file
  3. b3f9d2e  2026-03-16 04:34  antes do terminal: sed -i s/old/new/ config.py  (1 arquivo, +1/-1)

Gerenciando o Store pelo Shell

Fora de uma sessão, você pode inspecionar e gerenciar o store de checkpoints com comandos CLI:

Comando	Descrição
hermes checkpoints	Mostra tamanho total, contagem de projetos, detalhamento por projeto
hermes checkpoints status	Igual ao checkpoints puro
hermes checkpoints list	Alias para status
hermes checkpoints prune	Força uma varredura: deleta órfãos/obsoletos, GC, aplica limite de tamanho
hermes checkpoints clear	Elimina toda a base de checkpoints (pede confirmação antes)
hermes checkpoints clear-legacy	Deleta apenas os arquivos legacy-* da migração v1

Opções de Configuração

Você pode ajustar o comportamento dos checkpoints em ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruptor principal (padrão: false — opt-in)
  max_snapshots: 20           # máximo de checkpoints por projeto
  max_total_size_mb: 500      # limite rígido no tamanho total do store
  max_file_size_mb: 10        # ignora qualquer arquivo único maior que isso
  auto_prune: true            # varredura na inicialização (ligado por padrão)
  retention_days: 7           # deleta entradas mais antigas que isso
  min_interval_hours: 24      # tempo mínimo entre auto-prunes

Uma nota importante: a varredura de auto-prune nunca deleta entradas “órfãs” (onde o diretório de trabalho não é encontrado). Isso porque um workdir ausente na inicialização pode significar um projeto deletado — ou um volume externo desmontado ou compartilhamento de rede que ainda não está disponível. A limpeza de órfãos só acontece via o comando explícito hermes checkpoints prune, que pede confirmação antes.

Para desabilitar tudo:

checkpoints:
  enabled: false
  auto_prune: false

Quando enabled: false, o Gerenciador de Checkpoints é um no-op e nunca tenta operações git. Quando auto_prune: false, o store cresce até você rodar manualmente hermes checkpoints prune.

Concluindo

Os checkpoints dão a você a confiança para deixar o Hermes trabalhar livremente, sabendo que você sempre pode voltar para um estado conhecido e bom. Seja experimentando refatorações, testando comandos arriscados, ou apenas querendo paz de espírito, o comando /rollback está do seu lado.

Experimente na sua próxima sessão — você pode descobrir que ele se torna uma parte essencial do seu fluxo de trabalho.