Checkpoints and rollback: undo the agent's file changes

What Checkpoints and rollback is for

Checkpoints give you a safety net when the agent edits files. With checkpoints on, Hermes snapshots the working directory into a shared shadow git repository before it makes changes, leaving your project's own .git untouched. During a session, /rollback lists checkpoints with change stats. From there you can preview a diff, restore one file, or restore a whole checkpoint while keeping your own hand-edits. Shell commands report store size and prune old data. Checkpoints are off by default, so turn them on for any project where an unwanted edit would hurt.

What you need

• git available on PATH (checkpoints are disabled without it)
• A project directory that is not your home or root folder and has fewer than 50,000 files

Set it up

1. 1

   Enable for one session with hermes chat --checkpoints

2. 2

   Or enable globally by setting checkpoints: enabled: true in ~/.hermes/config.yaml

3. 3

   Use /rollback to list checkpoints, /rollback diff <N> to preview, and /rollback <N> to restore

Check it works

• Run /rollback after the agent edits a file and confirm a checkpoint is listed
• Run hermes checkpoints status to see store size and live or orphaned projects
• After a restore, Hermes reports which files it restored and which hand-edits it kept

Limits and failure points

• Files over max_file_size_mb (default 10 MB) are excluded, and nested git repositories are not captured
• Diff and restore are refused when using container backends such as docker
• The store is capped by max_total_size_mb (default 500 MB), so older history is dropped over time

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.