Tutorial 30: Checkpoints & Rollback

This is part of the Hermes Agent official tutorial series. View all tutorials

Think of checkpoints like the “save point” in a video game — right before you do something risky (like deleting a boss’s loot or trying a crazy jump), the game quietly saves your progress. If things go wrong, you press one button and you’re back to safety. Hermes Agent does exactly this for your code projects.

---

Step 1: Turn On Checkpoints (It’s Off by Default)

Hermes Agent does not automatically save checkpoints — you have to switch it on. This is intentional, because storing snapshots uses disk space. You have two ways to enable it:

Option A: Just for one session — add --checkpoints when starting a chat:

hermes chat --checkpoints

Option B: For every session — edit ~/.hermes/config.yaml and add:

checkpoints:
  enabled: true

That’s it. Once enabled, Hermes will quietly snapshot your project before it does anything destructive.

---

Step 2: Know What Triggers a Snapshot

Hermes automatically creates a checkpoint before these actions:

• Writing or editing files (via write_file and patch tools)
• Dangerous terminal commands like:
  • rm, rmdir (delete files/folders)
  • cp, mv (copy/move — can overwrite)
  • sed -i, truncate, dd, shred (modify or destroy data)
  • Output redirects (> — overwrites a file)
  • git reset, git clean, git checkout (can wipe your changes)

Don’t worry about spam — Hermes creates at most one checkpoint per folder per conversation turn, so you won’t get hundreds of snapshots.

---

Step 3: Use /rollback to Undo Mistakes

The magic happens with the /rollback command. Here’s your cheat sheet:

Command	What it does
/rollback	Shows a list of all checkpoints with what changed
/rollback 3	Restores your project to checkpoint #3 (also undoes the chat turn that caused the mess)
/rollback diff 3	Shows you a preview of what would change before you commit
/rollback 3 myfile.py	Restores just one file from checkpoint #3

Try it: run /rollback first to see your options, then /rollback diff 2 to peek, and finally /rollback 2 to restore.

---

Step 4: Manage Your Checkpoint Storage

Over time, checkpoints pile up. Use these CLI commands outside a chat session:

hermes checkpoints              # Show total size and per-project breakdown
hermes checkpoints prune        # Clean up old/orphaned snapshots
hermes checkpoints clear        # Delete ALL checkpoints (it asks first!)

---

How It Works (The Simple Version)

Hermes keeps a secret shadow copy of your project in a hidden folder (~/.hermes/checkpoints/store/). It never touches your real .git folder. All your projects share this one store, and because git is smart about storing identical content only once, it doesn’t waste space duplicating files.

When a checkpoint is needed, Hermes:

1. Figures out which project the file belongs to
2. Saves a snapshot into the shared store
3. Tags it with a project label so you can find it later

---

Configuration Quick Tips

In ~/.hermes/config.yaml, you can also tweak:

checkpoints:
  enabled: true
  max_snapshots: 20        # Keep max 20 per project
  max_total_size_mb: 500    # Hard cap on total storage

---

Summary

Checkpoints are your undo button for real-world coding. Enable them, let Hermes save before risky operations, and use /rollback to travel back in time when something breaks. It’s a safety net that costs a little disk space but saves you from costly mistakes.

Next up: Tutorial 31 — “Multi-Agent Collaboration: Letting Multiple Agents Work Together” — we’ll explore how to split tasks across specialized agents and coordinate their work.