Checkpoints e `/rollback` — A Rede de Segurança do Seu Projeto

Checkpoints e /rollback — A Rede de Segurança do Seu Projeto

Já assistiu um agente de IA fazendo uma alteração e pensou: “Espera, eu não queria fazer isso”? Todos nós já passamos por isso. Por isso o Hermes Agent agora inclui uma rede de segurança integrada: checkpoints. Pense neles como pontos de salvamento em um videogame — snapshots do seu projeto tirados antes de operações arriscadas, prontos para restaurar com um único comando.

O Que São Checkpoints?

Checkpoints são snapshots automáticos do seu projeto tirados antes de operações destrutivas. Se o agente estiver prestes a deletar arquivos, sobrescrever código ou executar comandos de terminal arriscados, ele primeiro salva o estado atual. Depois, você pode reverter para qualquer um desses snapshots.

A melhor parte? O histórico .git do seu projeto real nunca é tocado. O Hermes usa um armazenamento sombra compartilhado em ~/.hermes/checkpoints/store/ — um repositório git separado que mantém tudo organizado e deduplicado entre projetos.

Começando: Ative os Checkpoints

Checkpoints são opt-in a partir da v2. A maioria dos usuários nunca precisa deles, e o armazenamento pode crescer com o tempo, então o padrão é desativado.

Ative para uma única sessão:

hermes chat --checkpoints

Ou ative globalmente em ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Quando o Hermes Tira um Checkpoint?

O Hermes tira snapshots 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

Não se preocupe com spam — o agente cria no máximo um checkpoint por diretório por turno, então sessões longas permanecem limpas.

Usando /rollback na Sessão

Com os checkpoints ativados, você ganha comandos de barra poderosos direto no seu chat:

Comando	O Que Faz
/rollback	Lista todos os checkpoints com estatísticas de alterações
/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 alterações entre o checkpoint N e agora
/rollback <N> <file>	Restaura um único arquivo do checkpoint N

Veja como é listar os checkpoints:

📸 Checkpoints para /path/to/project:

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

  /rollback <N>             restaura para o checkpoint N (mantém suas edições manuais)
  /rollback <N> --all       restauração completa, sobrescrevendo também suas edições manuais
  /rollback diff <N>        pré-visualiza alterações desde o checkpoint N
  /rollback <N> <file>      restaura um único arquivo do checkpoint N

Gerenciando o Armazenamento pelo Shell

Fora de uma sessão, use a CLI para inspecionar e gerenciar seu armazenamento de checkpoints:

hermes checkpoints              # Mostra tamanho, contagem de projetos, detalhamento
hermes checkpoints status       # Igual ao acima
hermes checkpoints list         # Alias para status
hermes checkpoints prune        # Limpeza forçada: órfãos, dados obsoletos, limite de tamanho
hermes checkpoints clear        # Deleta tudo (pergunta antes)
hermes checkpoints clear-legacy # Remove arquivos antigos de migração v1

Exemplo de saída:

Base de checkpoints: /home/voce/.hermes/checkpoints
Tamanho total:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Projetos:        12

  WORKDIR                                                       COMMITS    ÚLTIMO ACESSO  ESTADO
  /home/voce/code/hermes-agent                                        20       2h atrás  ativo
  /home/voce/code/experiments/rl-runner                                8       1d atrás  ativo
  /home/voce/code/old-prototype                                        3       9d atrás  órfão

Opções de Configuração

Ajuste os checkpoints em ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruptor principal (padrão: false)
  max_snapshots: 20           # máximo de checkpoints por projeto
  max_total_size_mb: 500      # limite rígido no tamanho total do armazenamento
  max_file_size_mb: 10        # ignora arquivos maiores que isso

  # Manutenção automática (ativada por padrão)
  auto_prune: true
  retention_days: 7
  min_interval_hours: 24

Quer desativar tudo?

checkpoints:
  enabled: false
  auto_prune: false

Como Funciona por Baixo dos Panos

Quando o Hermes detecta uma ferramenta prestes a modificar arquivos, ele:

1. Resolve a raiz do projeto para aquele arquivo
2. Inicializa ou reutiliza o armazenamento sombra compartilhado
3. Prepara as alterações, constrói uma árvore e faz commit em uma ref específica do projeto (refs/hermes/<project-hash>)

Essas refs formam seu histórico de checkpoints, prontos para inspeção e restauração via /rollback.

Considerações Finais

Checkpoints dão paz de espírito quando você deixa o agente trabalhar no seu código. Seja experimentando, refatorando ou apenas querendo uma rede de segurança, o /rollback te protege. Ative, esqueça, e descanse tranquilo sabendo que você sempre pode desfazer.

Bom código — e lembre-se, pontos de salvamento existem por um motivo!