Checkpoints und `/rollback` — Dein Sicherheitsnetz für riskante Operationen

Hast du schon einmal einem KI-Agenten dabei zugesehen, wie er einen Befehl wie rm -rf ausführt oder eine Datei überschreibt, und gedacht: „Ich hoffe wirklich, es weiß, was es tut“? Mit Hermes Agent v2 hast du jetzt ein richtiges Sicherheitsnetz — Checkpoints — die dein Projekt vor riskanten Operationen sichern und mit einem einzigen Befehl wiederherstellen können.

Das Beste daran? Es ist komplett opt-in. Die meisten Nutzer werden /rollback nie verwenden, und da der Shadow-Store mit der Zeit wachsen kann, ist die Funktion standardmäßig deaktiviert. Aber wenn du sie brauchst, ist sie ein Lebensretter.

Checkpoints aktivieren

Du kannst Checkpoints pro Sitzung mit einem einfachen Flag aktivieren:

hermes chat --checkpoints

Oder global in ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Das war’s. Sobald aktiviert, erstellt Hermes automatisch einen Snapshot deines Projekts, bevor etwas Destruktives passiert.

Was einen Checkpoint auslöst

Hermes erstellt automatisch einen Checkpoint vor:

Datei-Tools — write_file und patch
Destruktive Terminal-Befehle — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, Output-Umleitungen (>), sowie git reset/clean/checkout

Der Agent erstellt höchstens einen Checkpoint pro Verzeichnis und Turn, damit langlaufende Sitzungen nicht mit Snapshots gespammt werden und deinen Speicher aufblähen.

Wie es unter der Haube funktioniert

Die Magie passiert über einen internen Checkpoint Manager, der ein einziges gemeinsames Shadow-Git-Repository unter ~/.hermes/checkpoints/store/ verwaltet. Dein echtes Projekt-.git wird nie angefasst — alles lebt in diesem separaten Store.

So läuft der Ablauf:

Hermes erkennt, wenn Tools dabei sind, Dateien in deinem Arbeitsbaum zu verändern.
Einmal pro Konversations-Turn (pro Verzeichnis) wird eine sinnvolle Projektwurzel ermittelt.
Der gemeinsame Shadow-Store wird initialisiert oder wiederverwendet.
Dateien werden in einen projektspezifischen Index gestaged, ein Tree wird gebaut und in eine projektspezifische Ref (refs/hermes/<project-hash>) committet.

Da alle Projekte denselben Store nutzen, dedupliziert gits content-addressable Objektdatenbank über Projekte und Turns hinweg — so verschwendest du keinen Speicherplatz für identische Inhalte.

`/rollback` in der Sitzung verwenden

Sobald du in einer Sitzung mit aktivierten Checkpoints bist, stehen dir mehrere Slash-Befehle zur Verfügung:

Befehl	Beschreibung
`/rollback`	Alle Checkpoints mit Änderungsstatistiken auflisten
`/rollback <N>`	Zu Checkpoint N zurückkehren, eigene manuelle Änderungen bleiben erhalten (macht auch den letzten Chat-Turn rückgängig)
`/rollback <N> --all`	Komplette Wiederherstellung — überschreibt auch deine manuellen Änderungen
`/rollback diff <N>`	Diff zwischen Checkpoint N und aktuellem Zustand anzeigen
`/rollback <N> <file>`	Einzelne Datei aus Checkpoint N wiederherstellen

Wenn du /rollback ausführst, siehst du eine formatierte Liste wie diese:

📸 Checkpoints für /pfad/zum/projekt:

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

Den Store von der Shell aus verwalten

Außerhalb einer Sitzung kannst du den Checkpoint-Store mit CLI-Befehlen inspizieren und verwalten:

Befehl	Beschreibung
`hermes checkpoints`	Gesamtgröße, Projektanzahl, Aufschlüsselung pro Projekt anzeigen
`hermes checkpoints status`	Wie `checkpoints` ohne Argumente
`hermes checkpoints list`	Alias für `status`
`hermes checkpoints prune`	Bereinigung erzwingen: verwaiste/veraltete Einträge löschen, GC, Größenlimit durchsetzen
`hermes checkpoints clear`	Komplette Checkpoint-Basis löschen (mit Rückfrage)
`hermes checkpoints clear-legacy`	Nur die `legacy-*`-Archive aus der v1-Migration löschen

Konfigurationsoptionen

Du kannst das Checkpoint-Verhalten in ~/.hermes/config.yaml feinjustieren:

checkpoints:
  enabled: false              # Master-Schalter (Standard: false — opt-in)
  max_snapshots: 20           # Maximale Checkpoints pro Projekt
  max_total_size_mb: 500      # Hartes Limit für die Gesamtgröße des Stores
  max_file_size_mb: 10        # Einzelne Dateien größer als dies werden übersprungen
  auto_prune: true            # Bereinigung beim Start (standardmäßig aktiv)
  retention_days: 7           # Einträge älter als dies werden gelöscht
  min_interval_hours: 24      # Mindestzeit zwischen automatischen Bereinigungen

Ein wichtiger Hinweis: Die automatische Bereinigung löscht niemals „verwaiste“ Einträge (bei denen das Arbeitsverzeichnis nicht gefunden wird). Das liegt daran, dass ein fehlendes Arbeitsverzeichnis beim Start ein gelöschtes Projekt bedeuten könnte — oder ein nicht gemountetes externes Volume bzw. eine Netzwerkfreigabe, die noch nicht verfügbar ist. Die Bereinigung von verwaisten Einträgen erfolgt nur über den expliziten Befehl hermes checkpoints prune, der zuerst um Bestätigung fragt.

Um alles zu deaktivieren:

checkpoints:
  enabled: false
  auto_prune: false

Wenn enabled: false ist, ist der Checkpoint Manager ein No-op und führt niemals Git-Operationen aus. Wenn auto_prune: false ist, wächst der Store, bis du manuell hermes checkpoints prune ausführst.

Fazit

Checkpoints geben dir das Vertrauen, Hermes frei arbeiten zu lassen, in dem Wissen, dass du jederzeit zu einem bekannten, guten Zustand zurückkehren kannst. Ob du mit Refactorings experimentierst, riskante Befehle testest oder einfach nur Seelenfrieden willst — der /rollback-Befehl deckt deinen Rücken.

Probier es in deiner nächsten Sitzung aus — du wirst vielleicht feststellen, dass es ein wesentlicher Bestandteil deines Workflows wird.