Checkpoints and Rollback

Why This Exists

As your agent does more on its own -- editing files, running terminal commands, working unsupervised on a schedule -- the cost of a mistake goes up. Checkpoints give you an undo button specifically for that: a snapshot taken automatically right before anything destructive happens, so you can get back to where you were without relying on your own git discipline in the moment.

Turning It On

Checkpoints are opt-in and disabled by default. Enable per-session:

hermes chat --checkpoints

Or turn it on globally in config.yaml:

checkpoints:
  enabled: true

What Triggers a Snapshot

A checkpoint is taken automatically before:

• File modifications -- write_file and patch tool operations
• Destructive terminal commands -- rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, output redirects (>), and git operations like reset, clean, and checkout

Hermes takes at most one checkpoint per directory per conversation turn -- you will not end up with a flood of near-identical snapshots if the agent touches the same directory five times in one turn.

How the Mechanism Works

Underneath, Hermes uses a single shared shadow git repository at ~/.hermes/checkpoints/store/ that deduplicates content across every project you use it in -- it is not creating a separate git repo per project. When a tool modifies files, Hermes resolves the project root, stages the changes into a per-project index, and commits to a per-project reference: refs/hermes/<project-hash>. None of this touches your project's own .git directory or your real commit history.

Rolling Back

In-session, via slash commands:

/rollback                  # List all checkpoints with change statistics
/rollback <N>               # Restore to checkpoint N and undo the last chat turn
/rollback diff <N>          # Show what changed since checkpoint N
/rollback <N> <file>        # Restore just one file, not the whole checkpoint

The single-file restore form is worth knowing specifically: if an agent edit broke one file but you want to keep three other changes it made in the same turn, you do not have to roll back everything.

From outside a session:

hermes checkpoints          # Show total size and per-project breakdown
hermes checkpoints prune    # Force cleanup and garbage collection
hermes checkpoints clear    # Remove all checkpoints

Limits That Keep This From Growing Unbounded

• Directories with more than 50,000 files are skipped entirely
• Individual files larger than max_file_size_mb (default 10 MB) are excluded
• The total store size is capped (default 500 MB)
• A turn with no actual changes is not snapshotted -- no-op checkpoints are skipped
• Any error during the snapshot process is logged at debug level without interrupting the tool call that triggered it -- a checkpoint failure never blocks the work itself

What This Is Not

Checkpoints are not a replacement for your own git workflow or for the credential/execution sandboxing covered in Lesson 2's strict mode. They are a safety net specifically for the moment something goes visibly wrong and you want to get back to a known-good state quickly, without having to remember to commit before every risky agent operation yourself.

The next lesson covers skills -- how to teach Hermes new, reusable procedures rather than relying on it to figure out the same multi-step workflow from scratch every time.