# Checkpoints and rollback: undo the agent's file changes

> Snapshot your working directory before Hermes edits files, then preview or restore earlier states with /rollback.

Canonical: https://hermeswatcher.com/tools/checkpoints-rollback  
Kind: Capability · Security & permissions  
Last reviewed: Oct 20, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## What it 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

## Setting it up

1. Enable for one session with `hermes chat --checkpoints`
2. Or enable globally by setting checkpoints: enabled: true in ~/.hermes/config.yaml
3. Use `/rollback` to list checkpoints, `/rollback diff <N>` to preview, and `/rollback <N>` to restore

## How to 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

- 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

## Related workflows

- [Build a useful GitHub issue review](https://hermeswatcher.com/workflows/github-issue-review.md)

## Sources

- [Hermes Agent docs: Checkpoints and Rollback](https://hermes-agent.nousresearch.com/docs/user-guide/checkpoints-and-rollback)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt