Por Que Você Deveria se Importar com Checkpoints

Imagine que você pede ao Hermes para refatorar um grande pedaço do seu código e, no meio do caminho, percebe que a nova abordagem é um desastre. Sem checkpoints, você ficaria preso desfazendo mudanças manualmente ou vasculhando o histórico do git. Com checkpoints, você simplesmente digita /rollback e escolhe um ponto de restauração. É como uma máquina do tempo para o seu projeto.

A melhor parte? Checkpoints são completamente opcionais. Eles vêm desativados por padrão na v2, então se você nunca usá-los, nunca notará que existem. Mas quando precisar deles, serão um salva-vidas.

Ativando Checkpoints

Você tem duas maneiras de ativar essa rede de segurança:

Por sessão (apenas neste chat):

hermes chat --checkpoints

Globalmente (todas as sessões) — edite ~/.hermes/config.yaml:

checkpoints:
  enabled: true

O Que Dispara um Checkpoint?

O Hermes tira automaticamente um snapshot do seu projeto antes de qualquer operação destrutiva, incluindo:

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

Para evitar spam, o Hermes cria no máximo um checkpoint por diretório por turno. Assim, uma sessão longa não vai encher seu disco com centenas de snapshots.

A Mágica por Trás dos Bastidores

Aqui está a parte inteligente: o Hermes usa um único repositório git shadow compartilhado armazenado em ~/.hermes/checkpoints/store/. A pasta .git do seu projeto real nunca é tocada. Todos os projetos compartilham esse único armazenamento, e o sistema de endereçamento por conteúdo do git deduplica arquivos automaticamente entre projetos. Então, se dois projetos têm arquivos semelhantes, eles são armazenados apenas uma vez.

Usando `/rollback` Durante a Sessão

Com os checkpoints ativados, você pode usar estes comandos de barra durante um 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 (também desfaz o último turno do chat)
`/rollback <N> --all`	Restauração completa — sobrescreve suas edições manuais também
`/rollback diff <N>`	Pré-visualiza a diferença entre o checkpoint N e o estado atual
`/rollback <N> <arquivo>`	Restaura apenas um arquivo do checkpoint N

Quando você digita /rollback, verá algo 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 Armazenamento pelo Shell

Fora de uma sessão, você pode inspecionar e limpar o armazenamento de checkpoints:

hermes checkpoints              # Mostra tamanho total, contagem de projetos, detalhamento
hermes checkpoints status       # Igual ao acima
hermes checkpoints list         # Atalho para status
hermes checkpoints prune        # Limpeza forçada: exclui órfãos, GC, aplica limite de tamanho
hermes checkpoints clear        # Elimina toda a base de checkpoints (pede confirmação antes)
hermes checkpoints clear-legacy # Exclui apenas arquivos de migração da v1

Ajustando a Configuração

Você pode controlar tudo 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 do tamanho total do armazenamento
  max_file_size_mb: 10        # ignora arquivos maiores que isso
  auto_prune: true            # limpeza automática de entradas antigas na inicialização
  retention_days: 7           # mantém entradas acessadas dentro deste número de dias
  min_interval_hours: 24      # faz prune no máximo uma vez a cada este intervalo

Um detalhe inteligente: o auto-prune nunca exclui entradas órfãs (projetos cujo diretório de trabalho não existe mais). Isso porque um diretório ausente pode simplesmente significar um drive externo desmontado ou uma VPN ainda não conectada. A limpeza de órfãos só acontece via comando explícito hermes checkpoints prune, que pede confirmação antes.

Quando Você Deve Ativá-lo?

Se você está fazendo trabalho experimental, grandes refatorações ou aprendendo o Hermes, ative os checkpoints. O custo de armazenamento é modesto (graças à deduplicação), e a tranquilidade é imensa. Se você está apenas fazendo tarefas simples e seguras, deixe desativado e economize espaço em disco.

Checkpoints são uma daquelas funcionalidades que você vai esquecer que existem — até o momento em que precisar desesperadamente deles. E quando esse momento chegar, você vai agradecer por eles estarem lá.