Wiki · Features in depth
Checkpoints and rollback
Before the agent touches a file it can take a snapshot. Here is how to roll back, how your own edits stay safe and why it is not a backup.
📸
Before the agent touches a file it can take a snapshot. When something breaks you step back one move — without losing your own edits.
Two things to remember: checkpoints are off by default and they are
not backups. They are undo steps for the agent's work.
Enable them first
With checkpoints off no snapshots are taken at all — whatever happens, there is nothing to return to. Two options:
# once, for a single run
❯ hermes chat --checkpoints
# permanently in ~/.hermes/config.yaml
checkpoints:
enabled: true # master switch (default: false)
max_snapshots: 20 # snapshots per project
max_total_size_mb: 500 # cap on the whole store
max_file_size_mb: 10 # larger single files are skipped
When a snapshot is taken
| Before | Examples |
|---|---|
| File tools | Writing a file, editing a file |
| Destructive terminal commands | Deleting (rm, rmdir), moving and copying (mv, cp), in-place edits (sed -i), truncating (truncate, dd, shred), output redirection (>), git changes (reset, clean, checkout) |
At most one snapshot per directory per turn, so a long session does not fill the store with dozens of copies.
How you go back
| What you type | What it does |
|---|---|
/rollback | Lists the snapshots with change stats |
/rollback 3 | Restores checkpoint 3; your hand-edits stay, and the last chat turn is undone too |
/rollback 3 --all | Full restore — your hand-edits are overwritten as well |
/rollback diff 3 | Shows what changed since checkpoint 3 (changes nothing yet) |
/rollback 3 notes.md | Restores a single file from checkpoint 3 |
The listing looks roughly like this — each entry says what triggered it:
📸 Checkpoints for /var/www/my-site:
1. 4270a8c 2026-10-17 04:36 before patch (1 file, +1/−0)
2. eaf4c1f 2026-10-17 04:35 before write_file
3. b3f9d2e 2026-10-17 04:34 before terminal: sed -i s/old/new/ config.py
To inspect the store outside a session:
| Command | What for |
|---|---|
hermes checkpoints status | How much space snapshots take and for which projects |
hermes checkpoints prune | Manual sweep — deletes stale and orphaned data, enforces the size cap |
hermes checkpoints clear | Removes the whole store (asks first) |
Your own edits are kept
If you edit a file by hand after the agent touched it and then roll back, Hermes skips that file instead of overwriting it, and lists it separately:
✅ Restored to checkpoint a1b2c3d4: before write_file
↷ Kept your hand-edits: src/config.py, notes.md
To restore those too, use /rollback 1 --all
Only files the agent last wrote get reverted. Add --all when you really want everything
back.
What snapshots will not save you from
| Situation | What happens |
|---|---|
| The agent runs in a container (Docker and similar) | Paths belong to the container, not your machine — no checkpoints are taken and restore is refused. The same on the CLI, in chat, in the TUI and in the desktop app |
| A nested git repository inside the directory | Only a reference is stored, not its files. A full restore is refused (it will not claim success for files it never captured). Workaround: take the checkpoint inside the nested repository's own directory |
| A directory with more than 50,000 files | Skipped |
| The filesystem root or your home directory | Skipped (too broad) |
No git on the machine | Checkpoints are silently disabled |
| A file larger than 10 MB | Skipped |
Where the snapshots live
~/.hermes/checkpoints/
├── store/ # one shared store for all projects
├── .last_prune # marker of the last sweep
└── legacy-… # archive of the older layout
Housekeeping runs by itself in the background (snapshots of projects you have not touched for a
while are removed; maintenance runs at most once every few hours and never blocks startup). You can
trigger it by hand with hermes checkpoints prune.
Pitfalls from our systems
| What happened | What to do |
|---|---|
| Checkpoints were off and there was nothing to return to | The most common trap — off is the default. Enable them before you start working, not once it hurts |
| We treated snapshots as a backup | They are not. They cover only files the agent changed and have caps (20 per project, 500 MB). Real backup lives elsewhere |
--all overwrote our hand-edit | A restore without --all protects your edits — use it deliberately |
| Restore did not work in a container | Expected: paths belong to the container. In container mode rely on git or a backup outside the container |
| A snapshot existed but restore was refused | It probably contained a nested repository. Restore the other files individually (/rollback 1 notes.md) or keep snapshots from the nested repository |
| The checkpoint store grew into hundreds of megabytes | Lower the caps (max_snapshots, max_total_size_mb) and check hermes checkpoints status |
Our tips
| Tip | Why |
|---|---|
Run /rollback diff before restoring | You see exactly what is about to disappear and pick the right snapshot |
| Use git for projects that already have history | Checkpoints are a safety net for the agent's work, not a replacement for git |
| Enable them where the agent actually writes files | In read-only projects they are pointless |
| Keep a copy outside the project for important work | Snapshots protect against an agent mistake, not a dead disk |