hermes checkpoints Command — Complete Reference & Examples

Overview

hermes checkpoints manages the filesystem checkpoint store — the shadow git repository that Hermes uses for the /rollback feature. Before Hermes performs write operations such as write_file, patch, or terminal calls, it snapshots the working directory. This command lets you inspect the store, prune stale data, or clear it entirely.

hermes checkpoints COMMAND

Subcommands

status — Inspect the checkpoint store

hermes checkpoints status

Shows the total size of the checkpoint base, how many projects are tracked, and a per-project breakdown.

list — Alias for status

hermes checkpoints list

Identical to status; use whichever name you prefer.

prune — Remove stale checkpoints

hermes checkpoints prune

Deletes orphan and stale checkpoints and runs garbage collection on the store. This reclaims disk space without removing the entire rollback history.

clear — Remove all checkpoints

hermes checkpoints clear

Deletes the entire checkpoint base, including all /rollback history. Use this only when you are sure you no longer need to roll back past operations.

clear-legacy — Delete v1 migration archives

hermes checkpoints clear-legacy

Removes only the legacy-<timestamp>/ archives left over from the v1 checkpoint migration.

Common Scenarios

Check disk usage

hermes checkpoints status

Use this to see how much space the checkpoint store is consuming and which projects contribute the most.

Routine cleanup

hermes checkpoints prune

Run this periodically to garbage-collect stale checkpoints and free disk space.

Start fresh after a major milestone

hermes checkpoints clear

Use when you have committed or backed up your work and no longer need rollback coverage for older changes.

Remove old migration archives

hermes checkpoints clear-legacy

Safe to run after upgrading from the v1 checkpoint format if you no longer need the migration backups.

Tips

• Checkpoints are the data source for the in-session /rollback command — clearing them removes rollback capability for past operations.
• prune is safer than clear because it only removes stale/orphan data.
• Large refactor sessions can generate many checkpoints; monitor store size with status.
• clear-legacy does not affect current checkpoints — only old migration archives.