Checkpoints & rollback

When the agent is editing files, it can automatically snapshot your project right before a destructive operation, so a single command undoes a bad change. This is a filesystem safety net that sits alongside (and independent of) your real git history.

Opt-in by default

Checkpoints are off by default as of v2, the shadow store grows over time and most sessions never need a rollback. Turn it on per-session or globally:

hermes chat --checkpoints

# ~/.hermes/config.yaml
checkpoints:
  enabled: true

Your real project .git is never touched. Snapshots live in a single shared shadow git repo at ~/.hermes/checkpoints/store/, where git's content-addressable storage deduplicates across projects and turns.

What triggers a checkpoint

Automatically, before:

• File tools: write_file, patch.
• Destructive terminal commands: rm, mv, cp, sed -i, truncate, dd, output redirects (>), git reset/clean/checkout.

At most one checkpoint per directory per turn, so long sessions don't spam snapshots.

Using /rollback

Inside a session:

Command	Description
/rollback	List all checkpoints with change stats
/rollback diff <N>	Preview the diff between checkpoint N and now
/rollback <N>	Restore to checkpoint N (also undoes the last chat turn)
/rollback <N> <file>	Restore a single file from checkpoint N

When you restore, Hermes first takes a pre-rollback snapshot (so you can undo the undo), restores the files, and rewinds the last conversation turn so the agent's context matches the filesystem.

TIP

Always /rollback diff <N> before restoring, it shows exactly what will change so you pick the right checkpoint. Use /rollback instead of git reset when you only want to undo agent-driven changes.

Managing the store from the shell

hermes checkpoints          # total size, project count, per-project breakdown
hermes checkpoints prune     # force a sweep: drop orphans/stale, enforce size cap
hermes checkpoints clear     # nuke the entire store (asks first)

Configuration

# ~/.hermes/config.yaml
checkpoints:
  enabled: false          # master switch (default off)
  max_snapshots: 20        # per project
  max_total_size_mb: 500   # hard cap; oldest commits dropped when exceeded
  max_file_size_mb: 10     # skip files larger than this
  auto_prune: true         # sweep stale/orphaned entries at startup
  retention_days: 7

Built-in guards

• If git isn't on PATH, checkpoints silently disable.
• Overly broad directories (/, $HOME) and repos with more than 50,000 files are skipped.
• Files larger than max_file_size_mb are excluded, so datasets and model weights don't get swallowed.
• No-change turns produce no snapshot.

Combine with git worktrees

For maximum safety when the agent does big refactors, keep each session in its own git branch or worktree, with checkpoints as an extra layer on top.