Tutorial 10: Checkpoints — AI's Undo Button | Easy Understand Hermes Agent

Imagine you’re editing a photo and accidentally hit “Save” after a mistake — wouldn’t it be great to have an undo button for your whole project? That’s exactly what Checkpoints do for Hermes Agent. It’s like a time machine for your code, letting you rewind to a safe moment before the AI does something risky.

Step 1: Turn On the Safety Net

By default, checkpoints are off (opt-in). Why? Because they use extra disk space, and most people never need them. But when you’re experimenting with big refactors or letting the agent run wild, they’re a lifesaver.

Turn it on for one session:

hermes chat --checkpoints

Or turn it on forever by editing ~/.hermes/config.yaml:

checkpoints:
  enabled: true

That’s it. Once enabled, Hermes automatically snaps a “before” picture of your files right before it does anything destructive.

Step 2: Know What Triggers a Snapshot

Hermes is smart about when to take a checkpoint. It only does it right before something that could break things:

Editing files — like write_file or patch
Dangerous terminal commands — like rm, mv, cp, sed -i, truncate, or even redirecting output with >
Git operations — like git reset, git clean, or git checkout

But here’s the clever part: it takes at most one checkpoint per folder per conversation turn. So if the agent runs 10 commands in the same directory, you get one snapshot, not ten. No spam.

Step 3: Use the Undo Button

When something goes wrong, you have two ways to roll back.

Inside a chat session, use slash commands:

/rollback              # see all checkpoints with stats
/rollback 3            # restore to checkpoint #3 (also undoes that chat turn)
/rollback diff 3       # preview what changed between now and checkpoint #3
/rollback 3 myfile.py  # restore just one file from checkpoint #3

Outside a session, use the CLI to manage the storage:

hermes checkpoints              # show total size and per-project breakdown
hermes checkpoints prune        # clean up old/stale snapshots
hermes checkpoints clear        # delete everything (it asks first!)

Step 4: Where Does It Store Everything?

Here’s the magic: Hermes never touches your real .git history. Instead, it keeps a single shared “shadow” git repository hidden at ~/.hermes/checkpoints/store/.

Every project you work on shares this one store. Because git is content-addressable, if two projects have the same file, it’s stored once, not twice. This keeps disk usage surprisingly small even across many projects.

Step 5: Tweak the Limits (Optional)

You can control how much space checkpoints eat up in ~/.hermes/config.yaml:

checkpoints:
  enabled: true
  max_snapshots: 20          # max checkpoints per project
  max_total_size_mb: 500     # hard cap on total store size
  max_file_size_mb: 10       # don't snapshot files bigger than this

Once you hit a limit, Hermes automatically drops the oldest snapshots to make room.

The Bottom Line

Checkpoints are your AI’s undo button. They’re off by default to save space, but turning them on is a one-line change. When you’re doing risky work — refactoring, deleting files, or letting the agent run multi-step commands — enable them and sleep easy. If something breaks, just /rollback and you’re back to safety.

Next up: Tutorial 11 — How to Debug Agent Loops Without Losing Your Mind. We’ll show you how to trace what the agent is thinking and catch infinite loops before they burn your API credits.