Checkpoints and Rollback for Agent File Edits

Hermes checkpoints provide an opt-in recovery layer around file mutations. Before supported write or destructive operations, Hermes can snapshot the working directory into a shared shadow Git store without changing the project’s real repository.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback

Enable deliberately

Checkpoints are off by default. Enable them for one session with hermes chat --checkpoints, or set checkpoints.enabled: true in config.yaml. The store lives below ~/.hermes/checkpoints/ and deduplicates objects across projects.

Use /rollback to list snapshots, /rollback diff <N> to inspect the delta, /rollback <N> <file> for a single-file restore, and /rollback <N> for a broader restore. Preview first whenever possible.

Safety checklist

Enable checkpoints only where the storage and recovery benefit justify them.
Set limits for snapshots, total size, and individual file size.
Keep automatic pruning enabled unless another maintenance process owns it.
Preview a rollback diff before restoring.
Prefer a single-file restore when the rest of the turn is valid.
Keep normal Git commits and backups for durable history.
Inspect checkpoint status periodically.
Test recovery on a disposable project before relying on it.

Pitfalls

Assuming checkpoints are enabled because the slash command exists.
Treating a shadow snapshot as a remote backup.
Restoring an entire checkpoint when only one file is wrong.
Disabling pruning and letting the shared store grow without a cap.
Expecting files above the configured size limit to be recoverable.

Verification steps

Enable checkpoints in a disposable directory.
Apply a small file edit with a Hermes file tool.
Run /rollback and confirm the pre-edit checkpoint appears.
Preview it with /rollback diff 1.
Restore one test file and verify its content.
Run hermes checkpoints status and inspect project and size accounting.
Run a safe prune and confirm live project history remains usable.