Checkpoint e `/rollback` — La Rete di Sicurezza del Tuo Progetto

Checkpoint e /rollback — La Rete di Sicurezza del Tuo Progetto

Ti è mai capitato di guardare un agente AI fare una modifica e pensare: “Ehi, non volevo fare questo”? Ci siamo passati tutti. Per questo Hermes Agent ora include una rete di sicurezza integrata: i checkpoint. Pensali come ai punti di salvataggio in un videogioco: istantanee del tuo progetto scattate prima di operazioni rischiose, pronte da ripristinare con un singolo comando.

Cosa Sono i Checkpoint?

I checkpoint sono istantanee automatiche del tuo progetto scattate prima di operazioni distruttive. Se l’agente sta per eliminare file, sovrascrivere codice o eseguire comandi terminale rischiosi, prima salva lo stato corrente. In seguito, puoi tornare a una qualsiasi di queste istantanee.

La parte migliore? La storia .git del tuo progetto reale non viene mai toccata. Hermes utilizza un archivio shadow condiviso in ~/.hermes/checkpoints/store/ — un repository git separato che mantiene tutto organizzato e deduplicato tra i progetti.

Per Iniziare: Attiva i Checkpoint

I checkpoint sono facoltativi a partire dalla v2. La maggior parte degli utenti non ne ha mai bisogno, e lo storage può crescere nel tempo, quindi di default sono disattivati.

Attivali per una singola sessione:

hermes chat --checkpoints

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

checkpoints:
  enabled: true

Quando Hermes Scatta un Checkpoint?

Hermes scatta automaticamente un’istantanea 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

Niente paura per lo spam: l’agente crea al massimo un checkpoint per directory per turno, così le sessioni lunghe restano pulite.

Usare /rollback in Sessione

Una volta attivati i checkpoint, hai a disposizione potenti comandi slash direttamente nella chat:

Comando	Cosa Fa
/rollback	Elenca tutti i checkpoint con le statistiche delle modifiche
/rollback <N>	Ripristina al checkpoint N, mantenendo le tue modifiche manuali
/rollback <N> --all	Ripristino completo — sovrascrive anche le tue modifiche manuali
/rollback diff <N>	Anteprima delle modifiche tra il checkpoint N e adesso
/rollback <N> <file>	Ripristina un singolo file dal checkpoint N

Ecco come appare l’elenco dei checkpoint:

📸 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)

  /rollback <N>             ripristina al checkpoint N (mantiene le tue modifiche manuali)
  /rollback <N> --all       ripristino completo, sovrascrive anche le tue modifiche manuali
  /rollback diff <N>        anteprima delle modifiche dal checkpoint N
  /rollback <N> <file>      ripristina un singolo file dal checkpoint N

Gestire lo Store dalla Shell

Fuori da una sessione, usa la CLI per ispezionare e gestire il tuo store di checkpoint:

hermes checkpoints              # Mostra dimensione, conteggio progetti, dettagli
hermes checkpoints status       # Come sopra
hermes checkpoints list         # Alias per status
hermes checkpoints prune        # Pulizia forzata: orfani, dati obsoleti, limite dimensione
hermes checkpoints clear        # Elimina tutto (chiede conferma prima)
hermes checkpoints clear-legacy # Rimuovi archivi di migrazione v1 obsoleti

Esempio di output:

Base checkpoint: /home/you/.hermes/checkpoints
Dimensione totale:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Progetti:        12

  WORKDIR                                                       COMMITS    ULTIMO ACCESSO  STATO
  /home/you/code/hermes-agent                                        20       2h fa  live
  /home/you/code/experiments/rl-runner                                8       1g fa  live
  /home/you/code/old-prototype                                        3       9g fa  orfano

Opzioni di Configurazione

Regola fine dei checkpoint in ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruttore principale (default: false)
  max_snapshots: 20           # max checkpoint per progetto
  max_total_size_mb: 500      # limite massimo dimensione totale store
  max_file_size_mb: 10        # salta file più grandi di questo

  # Manutenzione automatica (attiva di default)
  auto_prune: true
  retention_days: 7
  min_interval_hours: 24

Vuoi disattivare tutto?

checkpoints:
  enabled: false
  auto_prune: false

Come Funziona Sotto il Cofano

Quando Hermes rileva uno strumento che sta per modificare file,:

1. Risolve la root del progetto per quel file
2. Inizializza o riutilizza lo store shadow condiviso
3. Prepara le modifiche, costruisce un albero e committa su un ref per progetto (refs/hermes/<project-hash>)

Questi ref formano la tua cronologia di checkpoint, pronta per essere ispezionata e ripristinata tramite /rollback.

Considerazioni Finali

I checkpoint ti danno tranquillità quando lasci che l’agente lavori sul tuo codice. Che tu stia sperimentando, rifattorizzando, o semplicemente voglia una rete di sicurezza, /rollback ti copre le spalle. Attivalo, dimenticatene, e stai sereno sapendo che puoi sempre annullare.

Buon coding — e ricorda, i punti di salvataggio esistono per un motivo!