Perché Dovresti Interessarti ai Checkpoint

Immagina di chiedere a Hermes di rifattorizzare una grossa parte del tuo codice e, a metà strada, di renderti conto che il nuovo approccio è un disastro. Senza i checkpoint, saresti bloccato a dover annullare manualmente le modifiche o a scavare nella storia di git. Con i checkpoint, basta digitare /rollback e scegliere un punto di ripristino. È come una macchina del tempo per il tuo progetto.

La parte migliore? I checkpoint sono completamente opzionali. Nella v2 sono disattivati di default, quindi se non li usi mai, non noterai nemmeno che esistono. Ma quando ti servono, sono un vero salvavita.

Attivare i Checkpoint

Hai due modi per attivare questa rete di sicurezza:

Per sessione (solo questa chat):

hermes chat --checkpoints

Globalmente (tutte le sessioni) — modifica ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Cosa Attiva un Checkpoint?

Hermes crea automaticamente uno snapshot del tuo progetto prima di qualsiasi operazione distruttiva, tra cui:

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

Per evitare spam, Hermes crea al massimo un checkpoint per directory per turno. Quindi una sessione lunga non riempirà il tuo disco con centinaia di snapshot.

La Magia Dietro le Quinte

Ecco la parte intelligente: Hermes usa un unico repository git shadow condiviso archiviato in ~/.hermes/checkpoints/store/. La cartella .git del tuo progetto reale non viene mai toccata. Tutti i progetti condividono questo unico store, e il sistema di indirizzamento per contenuto di git deduplica automaticamente i file tra i progetti. Quindi se due progetti hanno file simili, vengono archiviati una sola volta.

Usare `/rollback` in Sessione

Una volta attivati i checkpoint, puoi usare questi comandi slash durante una chat:

Comando	Cosa fa
`/rollback`	Elenca tutti i checkpoint con statistiche sulle 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 solo un singolo file dal checkpoint N

Quando digiti /rollback, vedrai qualcosa del genere:

📸 Checkpoint per /percorso/al/progetto:

  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 ripulire lo store dei checkpoint:

hermes checkpoints              # Mostra dimensione totale, numero di progetti, dettagli
hermes checkpoints status       # Come sopra
hermes checkpoints list         # Alias per status
hermes checkpoints prune        # Pulizia forzata: elimina orfani, garbage collection, applica limite di dimensione
hermes checkpoints clear        # Elimina completamente l'intera base dei checkpoint (chiede conferma)
hermes checkpoints clear-legacy # Elimina solo gli archivi di migrazione v1

Ottimizzare la Configurazione

Puoi controllare tutto in ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruttore principale (default: false)
  max_snapshots: 20           # numero massimo di checkpoint per progetto
  max_total_size_mb: 500      # limite massimo per la dimensione totale dello store
  max_file_size_mb: 10        # salta i file più grandi di questa dimensione
  auto_prune: true            # pulizia automatica delle vecchie voci all'avvio
  retention_days: 7           # mantieni le voci toccate entro questo numero di giorni
  min_interval_hours: 24      # esegui la pulizia al massimo una volta in questo intervallo

Un dettaglio intelligente: l’auto-prune non elimina mai le voci orfane (progetti la cui directory di lavoro non esiste più). Questo perché una directory mancante potrebbe semplicemente significare un disco esterno non montato o una VPN non ancora connessa. La pulizia degli orfani avviene solo tramite il comando esplicito hermes checkpoints prune, che chiede conferma prima di procedere.

Quando Dovresti Attivarli?

Se stai facendo lavoro sperimentale, grandi refactoring, o stai imparando Hermes, attiva i checkpoint. Il costo in termini di spazio è contenuto (grazie alla deduplicazione), e la tranquillità è enorme. Se stai solo facendo compiti semplici e sicuri, lasciali disattivati e risparmia spazio su disco.

I checkpoint sono una di quelle funzionalità di cui ti dimentichi — finché non ne hai disperatamente bisogno. E quando quel momento arriva, sarai felice che ci siano.