Why You Should Care About Checkpoints

Por Qué Deberías Importarte los Checkpoints

Imagina que le pides a Hermes que refactorice una gran parte de tu código y, a mitad de camino, te das cuenta de que el nuevo enfoque es un desastre. Sin checkpoints, te quedarías atascado deshaciendo cambios manualmente o rebuscando en el historial de git. Con checkpoints, solo escribes /rollback y eliges un punto de restauración. Es como una máquina del tiempo para tu proyecto.

¿La mejor parte? Los checkpoints son completamente opcionales. Están desactivados por defecto en v2, así que si nunca los usas, nunca notarás que existen. Pero cuando los necesitas, son un salvavidas.

Activando los Checkpoints

Tienes dos formas de activar esta red de seguridad:

Por sesión (solo este chat):

hermes chat --checkpoints

Globalmente (todas las sesiones) — edita ~/.hermes/config.yaml:

checkpoints:
  enabled: true

¿Qué Activa un Checkpoint?

Hermes automáticamente toma una instantánea de tu proyecto antes de cualquier operación destructiva, incluyendo:

• Herramientas de archivos — write_file y patch
• Comandos de terminal peligrosos — rm, rmdir, cp, mv, sed -i, truncate, dd, shred, redirecciones de salida (>), y git reset/clean/checkout

Para evitar spam, Hermes crea como máximo un checkpoint por directorio por turno. Así, una sesión larga no llenará tu disco con cientos de instantáneas.

La Magia Detrás de Escena

Aquí está la parte ingeniosa: Hermes usa un único repositorio git oculto compartido almacenado en ~/.hermes/checkpoints/store/. La carpeta .git de tu proyecto real nunca se toca. Cada proyecto comparte este único almacén, y el sistema de direccionamiento por contenido de git automáticamente deduplica archivos entre proyectos. Así que si dos proyectos tienen archivos similares, solo se almacenan una vez.

Usando /rollback en la Sesión

Una vez que los checkpoints están activados, puedes usar estos comandos de barra durante un chat:

Comando	Qué hace
/rollback	Lista todos los checkpoints con estadísticas de cambios
/rollback <N>	Restaura al checkpoint N, conservando tus ediciones manuales (también deshace el último turno del chat)
/rollback <N> --all	Restauración completa — sobrescribe también tus ediciones manuales
/rollback diff <N>	Previsualiza la diferencia entre el checkpoint N y el estado actual
/rollback <N> <archivo>	Restaura solo un archivo desde el checkpoint N

Cuando escribes /rollback, verás algo como:

📸 Checkpoints para /ruta/al/proyecto:

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

Gestionando el Almacén desde la Terminal

Fuera de una sesión, puedes inspeccionar y limpiar el almacén de checkpoints:

hermes checkpoints              # Muestra el tamaño total, número de proyectos, desglose
hermes checkpoints status       # Igual que el anterior
hermes checkpoints list         # Alias para status
hermes checkpoints prune        # Limpieza forzada: elimina huérfanos, GC, aplica límite de tamaño
hermes checkpoints clear        # Borra toda la base de checkpoints (pide confirmación)
hermes checkpoints clear-legacy # Elimina solo los archivos de migración v1

Ajustando la Configuración

Puedes controlar todo en ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruptor principal (por defecto: false)
  max_snapshots: 20           # máximo de checkpoints por proyecto
  max_total_size_mb: 500      # límite duro del tamaño total del almacén
  max_file_size_mb: 10        # omite archivos más grandes que esto
  auto_prune: true            # limpieza automática de entradas antiguas al inicio
  retention_days: 7           # conserva entradas modificadas dentro de estos días
  min_interval_hours: 24      # ejecuta prune como máximo una vez en este intervalo

Un detalle inteligente: el auto-prune nunca elimina entradas huérfanas (proyectos cuyo directorio de trabajo ya no existe). Esto se debe a que un directorio faltante podría simplemente significar un disco externo desmontado o una VPN aún no conectada. La limpieza de huérfanos solo ocurre mediante el comando explícito hermes checkpoints prune, que pide confirmación primero.

¿Cuándo Deberías Activarlo?

Si estás haciendo trabajo experimental, refactorizaciones grandes, o aprendiendo Hermes, activa los checkpoints. El costo de almacenamiento es moderado (gracias a la deduplicación), y la tranquilidad es enorme. Si solo estás haciendo tareas simples y seguras, déjalo desactivado y ahorra espacio en disco.

Los checkpoints son una de esas funciones que olvidarás — hasta el momento en que las necesitas desesperadamente. Y cuando ese momento llegue, te alegrarás de que estén ahí.

---