Checkpoints and /rollback

Hermes Agent can automatically snapshot your project before destructive operations and restore it with a single command. Checkpoints are opt-in as of v2 — most users never use /rollback, and the shadow-store storage is non-trivial over time, so the default is off.

Enable checkpoints per-session with --checkpoints:

hermes chat --checkpoints

Or enable globally in ~/.hermes/config.yaml:

checkpoints:
  enabled: true

This safety net is powered by an internal Checkpoint Manager that keeps a single shared shadow git repository under ~/.hermes/checkpoints/store/ — your real project .git is never touched. Every project the agent works in shares the same store, so git's content-addressable object DB deduplicates across projects and across turns.

What Triggers a Checkpoint

Checkpoints are taken automatically before:

• File tools — write_file and patch
• Destructive terminal commands — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, output redirects (>), and git reset/clean/checkout

The agent creates at most one checkpoint per directory per turn, so long-running sessions don't spam snapshots.

Quick Reference

In-session slash commands:

CLI for inspecting and managing the store outside a session:

How Checkpoints Work

At a high level:

• Hermes detects when tools are about to modify files in your working tree.
• Once per conversation turn (per directory), it:
  • Resolves a reasonable project root for the file.
  • Initialises or reuses the single shared shadow store at ~/.hermes/checkpoints/store/.
  • Stages into a per-project index, builds a tree, and commits to a per-project ref (refs/hermes/<project-hash>).
• These per-project refs form a checkpoint history that you can inspect and restore via /rollback.

flowchart LR
  user["User command\n(hermes, gateway)"]
  agent["AIAgent\n(run_agent.py)"]
  tools["File & terminal tools"]
  cpMgr["CheckpointManager"]
  store["Shared shadow store\n~/.hermes/checkpoints/store/"]

  user --> agent
  agent -->|"tool call"| tools
  tools -->|"before mutate\nensure_checkpoint()"| cpMgr
  cpMgr -->|"git add/commit-tree/update-ref"| store
  cpMgr -->|"OK / skipped"| tools
  tools -->|"apply changes"| agent

Configuration

Configure in ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # master switch (default: false — opt-in)
  max_snapshots: 20           # max checkpoints per project (enforced via ref rewrite + gc)
  max_total_size_mb: 500      # hard cap on total store size; oldest commits dropped
  max_file_size_mb: 10        # skip any single file larger than this

  # Auto-maintenance (on by default): sweep ~/.hermes/checkpoints/ at startup
  # and delete project entries whose last_touch is older than retention_days.
  # Runs at most once per min_interval_hours, tracked via a .last_prune
  # marker. This sweep never deletes "orphan" entries (working directory not
  # found) — a missing workdir at startup is ambiguous (deleted project vs.
  # an unmounted external volume / network share / VPN not yet up), so
  # orphan cleanup is only ever done via the explicit
  # `hermes checkpoints prune` command below, with a confirmation prompt.
  auto_prune: true
  retention_days: 7
  min_interval_hours: 24

To disable everything:

checkpoints:
  enabled: false
  auto_prune: false

When enabled: false, the Checkpoint Manager is a no-op and never attempts git operations. When auto_prune: false, the store grows until you run hermes checkpoints prune manually.

Listing Checkpoints

From a CLI session:

/rollback

Hermes responds with a formatted list showing change statistics:

📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  before write_file
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

  /rollback <N>             restore to checkpoint N (keeps your hand-edits)
  /rollback <N> --all       full restore, overwriting your hand-edits too
  /rollback diff <N>        preview changes since checkpoint N
  /rollback <N> <file>      restore a single file from checkpoint N

Inspecting the Store from the Shell

hermes checkpoints

Sample output:

Checkpoint base: /home/you/.hermes/checkpoints
Total size:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Projects:        12

  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
  /home/you/code/hermes-agent                                        20       2h ago  live
  /home/you/code/experiments/rl-runner                                8       1d ago  live
  /home/you/code/old-prototype                                        3       9d ago  orphan
  ...

Legacy archives (1):
  legacy-20260506-050616                           4.2 MB

Clear with: hermes checkpoints clear-legacy

Force a full sweep (ignores the 24h idempotency marker):

hermes checkpoints prune --retention-days 3 --max-size-mb 200

Previewing Changes with /rollback diff

Before committing to a restore, preview what has changed since a checkpoint:

/rollback diff 1

This shows a git diff stat summary followed by the actual diff.

Restoring with /rollback

/rollback 1

Behind the scenes, Hermes:

1. Verifies the target commit exists in the shadow store.
2. Takes a pre-rollback snapshot of the current state so you can "undo the undo" later.
3. Restores tracked files in your working directory — preserving your hand-edits (see below).
4. Undoes the last conversation turn so the agent's context matches the restored filesystem state.

User hand-edits are preserved by default

/rollback <N> restores only the files Hermes itself changed. Every successful write_file / patch records the file's content hash in an agent-write ledger; at restore time, any file whose current contents no longer match what Hermes last wrote (you edited it afterwards, or Hermes never touched it) is skipped instead of overwritten, and listed in the output:

✅ Restored to checkpoint a1b2c3d4: before write_file
↷ Kept your hand-edits: src/config.py, notes.md
Use /rollback <N> --all to restore those too.

To force the classic full restore that reverts everything — including your own edits — add --all:

/rollback 1 --all

If the ledger is empty (a store created before this feature, or Hermes hasn't written any files in the project yet), /rollback falls back to the full restore automatically.

Single-File Restore

Restore just one file from a checkpoint without affecting the rest of the directory:

/rollback 1 src/broken_file.py

Safety and Performance Guards

• Git availability — if git is not found on PATH, checkpoints are transparently disabled.
• Directory scope — Hermes skips overly broad directories (root /, home $HOME).
• Repository size — directories with more than 50,000 files are skipped.
• Per-file size cap — files larger than max_file_size_mb (default 10 MB) are excluded from the snapshot. Prevents accidentally swallowing datasets, model weights, or generated media.
• Total store size cap — when the store exceeds max_total_size_mb (default 500 MB), the oldest commit per project is dropped round-robin until under the cap.
• Real pruning — max_snapshots is enforced by rewriting the per-project ref and running git gc --prune=now afterwards, so loose objects don't accumulate.
• No-change snapshots — if there are no changes since the last snapshot, the checkpoint is skipped.
• Non-fatal errors — all errors inside the Checkpoint Manager are logged at debug level; your tools continue to run.

Where Checkpoints Live

~/.hermes/checkpoints/
  ├── store/                 # single shared bare git repo
  │   ├── HEAD, objects/     # git internals (shared across projects)
  │   ├── refs/hermes/<hash> # per-project branch tip
  │   ├── indexes/<hash>     # per-project git index
  │   ├── projects/<hash>.json  # workdir + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # auto-prune idempotency marker
  └── legacy-<ts>/           # archived pre-v2 per-project shadow repos

Each <hash> is derived from the absolute path of the working directory. You normally never need to touch these manually — use hermes checkpoints status / prune / clear instead.

Migration from v1

Before the v2 rewrite, each working directory got its own complete shadow git repo directly under ~/.hermes/checkpoints/<hash>/. That layout couldn't dedup objects across projects and had a documented no-op pruner — the store would grow without bound.

On first v2 run, any pre-v2 shadow repos are moved into ~/.hermes/checkpoints/legacy-<timestamp>/ so the new single-store layout starts clean. Old /rollback history is still reachable by manually inspecting the legacy archive with git; once you're confident you don't need it, run:

hermes checkpoints clear-legacy

to reclaim the space. Legacy archives are also swept by auto_prune after retention_days.

Best Practices

• Enable checkpoints only when you need them — hermes chat --checkpoints or per-profile enabled: true.
• Use /rollback diff before restoring — preview what will change to pick the right checkpoint.
• Use /rollback instead of git reset when you want to undo agent-driven changes only.
• Check hermes checkpoints status occasionally if you use checkpoints regularly — shows which projects are active and what the store costs you.
• Combine with Git worktrees for maximum safety — keep each Hermes session in its own worktree/branch, with checkpoints as an extra layer.

For running multiple agents in parallel on the same repo, see the guide on Git worktrees.