Checkpoints y `/rollback` — La Red de Seguridad de Tu Proyecto

¿Alguna vez has visto a un agente de IA hacer un cambio y has pensado: “Espera, yo no quería hacer eso”? Todos hemos pasado por ahí. Por eso Hermes Agent ahora incluye una red de seguridad integrada: checkpoints. Piénsalo como puntos de guardado en un videojuego: instantáneas de tu proyecto tomadas antes de operaciones arriesgadas, listas para restaurar con un solo comando.

¿Qué Son los Checkpoints?

Los checkpoints son instantáneas automáticas de tu proyecto tomadas antes de operaciones destructivas. Si el agente está a punto de eliminar archivos, sobrescribir código o ejecutar comandos de terminal arriesgados, primero guarda el estado actual. Más tarde, puedes revertir a cualquiera de estas instantáneas.

¿La mejor parte? El historial .git real de tu proyecto nunca se toca. Hermes usa un almacén compartido oculto en ~/.hermes/checkpoints/store/ — un repositorio git separado que mantiene todo organizado y deduplicado entre proyectos.

Primeros Pasos: Activar Checkpoints

Los checkpoints son opt-in a partir de la v2. La mayoría de los usuarios nunca los necesitan, y el almacenamiento puede crecer con el tiempo, así que el valor predeterminado es estar desactivados.

Actívalos para una sola sesión:

hermes chat --checkpoints

O actívalos globalmente en ~/.hermes/config.yaml:

checkpoints:
  enabled: true

¿Cuándo Toma Hermes un Checkpoint?

Hermes toma instantáneas automáticamente antes de:

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

No te preocupes por el spam: el agente crea como máximo un checkpoint por directorio por turno, así que las sesiones largas se mantienen limpias.

Usando `/rollback` en la Sesión

Una vez que los checkpoints están activados, tienes poderosos comandos de barra directamente en tu chat:

Comando	Qué Hace
`/rollback`	Lista todos los checkpoints con estadísticas de cambios
`/rollback <N>`	Restaura al checkpoint N, conservando tus ediciones manuales
`/rollback <N> --all`	Restauración completa — también sobrescribe tus ediciones manuales
`/rollback diff <N>`	Previsualiza los cambios entre el checkpoint N y ahora
`/rollback <N> <archivo>`	Restaura un solo archivo desde el checkpoint N

Así es como se ve listar los checkpoints:

📸 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)

  /rollback <N>             restaurar al checkpoint N (conserva tus ediciones manuales)
  /rollback <N> --all       restauración completa, sobrescribiendo también tus ediciones manuales
  /rollback diff <N>        previsualizar cambios desde el checkpoint N
  /rollback <N> <archivo>   restaurar un solo archivo desde el checkpoint N

Gestionando el Almacén desde la Terminal

Fuera de una sesión, usa el CLI para inspeccionar y gestionar tu almacén de checkpoints:

hermes checkpoints              # Muestra tamaño, número de proyectos, desglose
hermes checkpoints status       # Igual que el anterior
hermes checkpoints list         # Alias de status
hermes checkpoints prune        # Limpieza forzada: huérfanos, datos obsoletos, límite de tamaño
hermes checkpoints clear        # Elimina todo (pide confirmación primero)
hermes checkpoints clear-legacy # Elimina archivos antiguos de migración v1

Ejemplo de salida:

Base de checkpoints: /home/tu/.hermes/checkpoints
Tamaño total:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Proyectos:        12

  WORKDIR                                                       COMMITS    ÚLTIMO ACCESO  ESTADO
  /home/tu/code/hermes-agent                                        20       2h atrás  activo
  /home/tu/code/experiments/rl-runner                                8       1d atrás  activo
  /home/tu/code/old-prototype                                        3       9d atrás  huérfano

Opciones de Configuración

Ajusta los checkpoints en ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruptor principal (predeterminado: false)
  max_snapshots: 20           # máximo de checkpoints por proyecto
  max_total_size_mb: 500      # límite máximo del tamaño total del almacén
  max_file_size_mb: 10        # omitir archivos más grandes que esto

  # Mantenimiento automático (activado por defecto)
  auto_prune: true
  retention_days: 7
  min_interval_hours: 24

¿Quieres desactivarlo todo?

checkpoints:
  enabled: false
  auto_prune: false

Cómo Funciona por Dentro

Cuando Hermes detecta que una herramienta está a punto de modificar archivos,:

Resuelve la raíz del proyecto para ese archivo
Inicializa o reutiliza el almacén oculto compartido
Prepara los cambios, construye un árbol y hace commit a una ref específica del proyecto (refs/hermes/<hash-del-proyecto>)

Estas refs forman tu historial de checkpoints, listo para inspección y restauración mediante /rollback.

Reflexiones Finales

Los checkpoints te dan tranquilidad cuando dejas que el agente trabaje en tu código. Ya sea que estés experimentando, refactorizando o simplemente quieras una red de seguridad, /rollback te cubre las espaldas. Actívalo, olvídate de él, y descansa tranquilo sabiendo que siempre puedes deshacer.

¡Feliz codificación! — y recuerda, los puntos de guardado existen por una razón.