Checkpoint e `/rollback` — La tua rete di sicurezza per le operazioni distruttive

Checkpoint e /rollback — La tua rete di sicurezza per le operazioni distruttive

Hai mai guardato un agente AI eseguire un comando come rm -rf o sovrascrivere un file pensando: “Spero davvero che sappia cosa sta facendo”? Con Hermes Agent v2, ora hai una vera rete di sicurezza — i checkpoint — che possono catturare un’istantanea del tuo progetto prima di operazioni rischiose e ripristinarla con un singolo comando.

La parte migliore? È completamente opt-in. La maggior parte degli utenti non tocca mai /rollback, e poiché lo shadow-store può crescere nel tempo, l’impostazione predefinita è disattivata. Ma quando ti serve, è un vero salvavita.

Abilitare i checkpoint

Puoi abilitare i checkpoint per sessione con un semplice flag:

hermes chat --checkpoints

Oppure abilitarli globalmente in ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Tutto qui. Una volta abilitati, Hermes cattura automaticamente un’istantanea del tuo progetto prima che accada qualcosa di distruttivo.

Cosa attiva un checkpoint

Hermes crea un checkpoint automaticamente prima di:

• Strumenti file — write_file e patch
• Comandi terminale distruttivi — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, reindirizzamenti di output (>), e git reset/clean/checkout

L’agente crea al massimo un checkpoint per directory per turno, così le sessioni lunghe non inondano di snapshot e non appesantiscono lo storage.

Come funziona dietro le quinte

La magia avviene tramite un Checkpoint Manager interno che mantiene un unico repository git shadow condiviso in ~/.hermes/checkpoints/store/. Il .git del tuo progetto reale non viene mai toccato — tutto vive in questo store separato.

Ecco il flusso:

1. Hermes rileva quando gli strumenti stanno per modificare file nel tuo working tree.
2. Una volta per turno di conversazione (per directory), risolve una radice del progetto ragionevole.
3. Inizializza o riutilizza lo shadow store condiviso.
4. Mette in stage i file in un indice per progetto, costruisce un tree e committa su un ref per progetto (refs/hermes/<project-hash>).

Poiché tutti i progetti condividono lo stesso store, il database di oggetti content-addressable di git deduplica tra progetti e tra turni — quindi non sprechi spazio su contenuti identici.

Usare /rollback in sessione

Una volta in una sessione con i checkpoint abilitati, hai diversi comandi slash a disposizione:

Comando	Descrizione
/rollback	Elenca tutti i checkpoint con statistiche delle modifiche
/rollback <N>	Ripristina al checkpoint N, mantenendo le tue modifiche manuali (annulla anche l’ultimo turno di chat)
/rollback <N> --all	Ripristino completo — sovrascrive anche le tue modifiche manuali
/rollback diff <N>	Anteprima del diff tra il checkpoint N e lo stato attuale
/rollback <N> <file>	Ripristina un singolo file dal checkpoint N

Quando esegui /rollback, vedrai un elenco formattato come questo:

📸 Checkpoint per /path/to/project:

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

Gestire lo store dalla shell

Fuori da una sessione, puoi ispezionare e gestire lo store dei checkpoint con i comandi CLI:

Comando	Descrizione
hermes checkpoints	Mostra dimensione totale, numero di progetti, ripartizione per progetto
hermes checkpoints status	Come il semplice checkpoints
hermes checkpoints list	Alias di status
hermes checkpoints prune	Forza una pulizia: elimina orfani/obsoleti, GC, applica il limite di dimensione
hermes checkpoints clear	Cancella l’intera base dei checkpoint (chiede conferma prima)
hermes checkpoints clear-legacy	Elimina solo gli archivi legacy-* dalla migrazione v1

Opzioni di configurazione

Puoi ottimizzare il comportamento dei checkpoint in ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruttore principale (default: false — opt-in)
  max_snapshots: 20           # max checkpoint per progetto
  max_total_size_mb: 500      # limite massimo sulla dimensione totale dello store
  max_file_size_mb: 10        # salta qualsiasi singolo file più grande di questo
  auto_prune: true            # pulizia all'avvio (attiva di default)
  retention_days: 7           # elimina le voci più vecchie di questo
  min_interval_hours: 24      # tempo minimo tra pulizie automatiche

Una nota importante: la pulizia automatica non elimina mai le voci “orfane” (dove la directory di lavoro non viene trovata). Questo perché una workdir mancante all’avvio potrebbe significare un progetto eliminato — o un volume esterno smontato o una condivisione di rete non ancora attiva. La pulizia degli orfani avviene solo tramite il comando esplicito hermes checkpoints prune, che chiede conferma prima.

Per disabilitare tutto:

checkpoints:
  enabled: false
  auto_prune: false

Quando enabled: false, il Checkpoint Manager è un no-op e non tenta mai operazioni git. Quando auto_prune: false, lo store cresce finché non esegui manualmente hermes checkpoints prune.

In sintesi

I checkpoint ti danno la fiducia per lasciare che Hermes lavori liberamente, sapendo che puoi sempre tornare a uno stato noto e funzionante. Che tu stia sperimentando con refactoring, testando comandi rischiosi, o semplicemente voglia la tranquillità mentale, il comando /rollback ti copre le spalle.

Provalo nella tua prossima sessione — potresti scoprire che diventa una parte essenziale del tuo flusso di lavoro.