Checkpoints and Rollback: Safety Nets for Destructive Operations

Hermes Agent can automatically snapshot your project before destructive operations and restore it with a single command. Independent of your own version control, checkpoints act as a safety net for the moments when an autonomous agent is about to delete, overwrite, or otherwise alter files in your working tree.

Checkpoints are opt-in as of v2. Because the shadow-store storage is non-trivial over time, the default is off, and most users never use /rollback at all. You enable it per-session with hermes chat --checkpoints, or globally in ~/.hermes/config.yaml:

checkpoints:
  enabled: true

What Triggers a Checkpoint

Snapshots are taken automatically, at most one per directory per turn so long-running sessions don't spam snapshots, before any operation that could harm your working tree:

• 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

How Checkpoints Work

The 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 database deduplicates across projects and across turns.

When tools are about to modify files, Hermes resolves a reasonable project root, creates or reuses the shared store, stages into a per-project index, builds a tree, and commits to a per-project ref (refs/hermes/<project-hash>). These refs form a checkpoint history you can inspect and restore.

The Command Line Interface

In-session slash commands make the workflow fast:

Outside a session, hermes checkpoints shows total size, project count, and per-project breakdown; hermes checkpoints prune forces a sweep of orphans and stale entries; hermes checkpoints clear nukes the entire base (after asking).

Hand-Edits Are Preserved by Default

One of the most useful behaviors is that /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 (because you edited it afterward, or Hermes never touched it) is skipped instead of overwritten and listed in the output. Pass --all to force a classic full restore that reverts everything, including your own edits.

You can also restore a single file without affecting the rest of the directory: /rollback 1 src/broken_file.py.

Safety and Performance Guards

The Checkpoint Manager is designed to stay out of the way and never do more harm than it prevents:

• Git availability — if git is not found on PATH, checkpoints are transparently disabled.
• Directory scope — overly broad directories (root /, home $HOME) are skipped.
• Repository size — directories with more than 50,000 files are skipped.
• Per-file cap — files larger than max_file_size_mb (default 10 MB) are excluded, preventing datasets, model weights, or generated media from being accidentally swallowed.
• Store cap — when the store exceeds max_total_size_mb (default 500 MB), the oldest commit per project is dropped round-robin.
• Real pruning — max_snapshots is enforced via ref rewrite plus git gc --prune=now, so loose objects don't accumulate.
• Non-fatal errors — all errors inside the manager are logged at debug level; your tools keep running.

Best Practices

Enable checkpoints only when you need them, and use /rollback diff before restoring to preview what will change. Prefer /rollback over git reset when you want to undo agent-driven changes only, and check hermes checkpoints status occasionally to see which projects are active and what the store costs. For maximum safety when running multiple agents in parallel on the same repo, combine checkpoints with Git worktrees — one session per worktree or branch, with checkpoints as an extra layer.

Key Takeaways

• Checkpoints auto-snapshot before write_file, patch, and destructive terminal commands, at most once per directory per turn.
• Restores preserve your hand-edits by default via an agent-write ledger; --all forces a full revert.
• A single shared shadow git repo under ~/.hermes/checkpoints/store/ never touches your real project .git and deduplicates across projects.
• Generous safety guards cap file size, store size, and directory scope, and disabled git makes checkpoints a transparent no-op.
• Use /rollback diff before restoring and pair with Git worktrees for the safest multi-agent setup.