Checkpoints y `/rollback` — Tu Red de Seguridad para Operaciones Destructivas

Checkpoints y /rollback — Tu Red de Seguridad para Operaciones Destructivas

¿Alguna vez has visto a un agente de IA ejecutar un comando como rm -rf o sobrescribir un archivo y has pensado: “espero que realmente sepa lo que está haciendo”? Con Hermes Agent v2, ahora tienes una red de seguridad adecuada — checkpoints — que pueden tomar una instantánea de tu proyecto antes de operaciones arriesgadas y restaurarlo con un solo comando.

¿La mejor parte? Es completamente opt-in. La mayoría de los usuarios nunca tocan /rollback, y dado que el almacenamiento shadow-store puede crecer con el tiempo, está desactivado por defecto. Pero cuando lo necesitas, es un salvavidas.

Habilitando Checkpoints

Puedes habilitar checkpoints por sesión con una simple bandera:

hermes chat --checkpoints

O habilitarlos globalmente en ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Eso es todo. Una vez habilitados, Hermes automáticamente toma una instantánea de tu proyecto antes de que ocurra algo destructivo.

Qué Activa un Checkpoint

Hermes toma un checkpoint 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

El agente crea como máximo un checkpoint por directorio por turno, para que las sesiones largas no generen instantáneas en exceso y abulten tu almacenamiento.

Cómo Funciona Internamente

La magia ocurre a través de un Checkpoint Manager interno que mantiene un único repositorio git shadow compartido en ~/.hermes/checkpoints/store/. Tu .git real del proyecto nunca se toca — todo vive en este almacén separado.

Este es el flujo:

1. Hermes detecta cuando las herramientas están a punto de modificar archivos en tu árbol de trabajo.
2. Una vez por turno de conversación (por directorio), resuelve una raíz de proyecto razonable.
3. Inicializa o reutiliza el almacén shadow compartido.
4. Prepara los archivos en un índice por proyecto, construye un árbol y hace commit a una ref por proyecto (refs/hermes/<project-hash>).

Dado que todos los proyectos comparten el mismo almacén, la base de datos de objetos direccionables por contenido de git deduplica entre proyectos y entre turnos — así no desperdicias espacio en contenido idéntico.

Usando /rollback en Sesión

Una vez que estás en una sesión con checkpoints habilitados, tienes varios comandos de barra a tu disposición:

Comando	Descripción
/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>	Vista previa del diff entre el checkpoint N y el estado actual
/rollback <N> <file>	Restaura un solo archivo desde el checkpoint N

Cuando ejecutas /rollback, verás una lista formateada como esta:

📸 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 gestionar el almacén de checkpoints con comandos CLI:

Comando	Descripción
hermes checkpoints	Muestra tamaño total, número de proyectos, desglose por proyecto
hermes checkpoints status	Igual que checkpoints sin argumentos
hermes checkpoints list	Alias de status
hermes checkpoints prune	Fuerza una limpieza: elimina huérfanos/obsoletos, ejecuta GC, aplica límite de tamaño
hermes checkpoints clear	Elimina toda la base de checkpoints (pide confirmación primero)
hermes checkpoints clear-legacy	Elimina solo los archivos legacy-* de la migración de v1

Opciones de Configuración

Puedes ajustar el comportamiento de los checkpoints en ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # interruptor principal (por defecto: false — opt-in)
  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        # omite cualquier archivo individual mayor que esto
  auto_prune: true            # limpieza al inicio (activada por defecto)
  retention_days: 7           # elimina entradas más antiguas que esto
  min_interval_hours: 24      # tiempo mínimo entre limpiezas automáticas

Una nota importante: la limpieza automática nunca elimina entradas “huérfanas” (donde el directorio de trabajo no se encuentra). Esto se debe a que un workdir ausente al inicio podría significar un proyecto eliminado — o un volumen externo desmontado o un recurso compartido de red que aún no está disponible. La limpieza de huérfanos solo ocurre mediante el comando explícito hermes checkpoints prune, que pide confirmación primero.

Para desactivar todo:

checkpoints:
  enabled: false
  auto_prune: false

Cuando enabled: false, el Checkpoint Manager es un no-op y nunca intenta operaciones git. Cuando auto_prune: false, el almacén crece hasta que ejecutes manualmente hermes checkpoints prune.

Conclusión

Los checkpoints te dan la confianza para dejar que Hermes trabaje libremente, sabiendo que siempre puedes volver a un estado conocido y bueno. Ya sea que estés experimentando con refactorizaciones, probando comandos arriesgados, o simplemente quieras tranquilidad, el comando /rollback te cubre las espaldas.

Pruébalo en tu próxima sesión — puede que descubras que se convierte en una parte esencial de tu flujo de trabajo.