Tutorial 10: Checkpoints — El botón de deshacer de la IA

¿Recuerdas esa sensación de hundimiento cuando te das cuenta de que acabas de borrar algo importante? Quizás era un archivo en el que pasaste horas, o un cambio de configuración que lo rompió todo. En el mundo real, no hay Ctrl+Z para tu sistema de archivos. Pero en Hermes Agent sí lo hay — y se llama checkpoints.

Piensa en los checkpoints como puntos de guardado en un videojuego. Antes de que tu agente de IA haga algo arriesgado — como sobrescribir un archivo o ejecutar un comando destructivo — puede tomar una instantánea rápida de tu proyecto. Si algo sale mal, puedes volver a esa instantánea con un solo comando. Es como tener un botón de deshacer para todo tu proyecto.

Activando la red de seguridad

Aquí va la verdad honesta: los checkpoints son opt-in en Hermes v2. La mayoría de los usuarios nunca los necesitan, y el almacenamiento puede crecer con el tiempo. Pero si estás trabajando en algo importante, son un salvavidas.

Tienes dos formas de activarlos:

Por sesión (solo para un chat):

hermes chat --checkpoints

Globalmente (en ~/.hermes/config.yaml):

checkpoints:
  enabled: true

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

¿Qué activa un checkpoint?

Hermes es inteligente a la hora de tomar instantáneas. Vigila:

Operaciones de archivos — como write_file y patch
Comandos de terminal destructivos — como rm, mv, sed -i, truncate, e incluso git reset o git clean

¿La mejor parte? Crea como máximo un checkpoint por directorio y por turno, así tus sesiones largas no generarán cientos de instantáneas.

Volver atrás: los comandos de barra

Cuando estás en una sesión de chat, /rollback es tu mejor amigo:

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

El /rollback <N> por defecto es inteligente — conserva cualquier cambio que hayas hecho a mano, deshaciendo solo lo que hizo el agente. Si quieres una limpieza completa, usa --all.

Gestionando el almacén desde la terminal

Fuera del chat, tienes comandos CLI para inspeccionar y gestionar tus checkpoints:

hermes checkpoints              # Muestra tamaño, proyectos, desglose
hermes checkpoints status       # Igual que el anterior
hermes checkpoints list         # Alias de status
hermes checkpoints prune        # Limpia huérfanos y datos obsoletos
hermes checkpoints clear        # Elimina todo (pide confirmación)
hermes checkpoints clear-legacy # Elimina archivos de migración v1 antiguos

Cómo funciona por dentro

Quizás te estés preguntando: “¿Esto interfiere con mi repositorio git real?” No. Hermes mantiene un “almacén sombra” separado en ~/.hermes/checkpoints/store/. Tu .git real del proyecto nunca se toca.

Todos tus proyectos comparten este único almacén, y como git usa direccionamiento por contenido, los archivos que aparecen en varios proyectos solo se guardan una vez. Es sorprendentemente eficiente.

Ajustando la configuración

Puedes controlar cuánto almacenamiento usan los checkpoints:

checkpoints:
  enabled: true
  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 archivos más grandes que esto
  auto_prune: true            # Limpieza automática de entradas antiguas
  retention_days: 7           # Conserva entradas durante 7 días
  min_interval_hours: 24      # Limpia como máximo una vez al día

La función de auto-prune es inteligente — limpia entradas antiguas al iniciar, pero nunca elimina entradas “huérfanas” (proyectos cuyas carpetas no se encuentran). Eso es porque una carpeta que falta podría significar simplemente que un disco externo aún no está montado. Para la limpieza de huérfanos, tendrás que ejecutar hermes checkpoints prune manualmente.

El botón de deshacer de tu proyecto

Los checkpoints te dan la confianza para dejar que tu agente de IA trabaje libremente, sabiendo que siempre puedes volver atrás en el tiempo. Ya sea que estés refactorizando código, experimentando con configuraciones, o simplemente quieras tranquilidad, vale la pena activarlos.

Pruébalos en tu próxima sesión con hermes chat --checkpoints. Quizás nunca necesites hacer rollback — pero si lo necesitas, te alegrará que estén ahí.