7. Checkpointing en Gemini CLI

Objetivo del tema

Entender cómo Gemini CLI crea puntos de control automáticos antes de ejecutar herramientas que modifican archivos, y cómo restaurar el proyecto a un estado anterior cuando algo no sale según lo esperado.

Seguimos las pautas de la documentación oficial (Checkpointing) para conocer rutas, comandos y buenas prácticas.

7.1 ¿Qué es y cómo funciona el checkpointing?

Cuando Gemini CLI prepara una acción potencialmente destructiva (por ejemplo, escribir en un archivo o ejecutar un script que modifica el repositorio), crea un checkpoint que captura:

• El estado de los archivos afectados.
• La conversación y contexto dentro del CLI.
• El prompt o comando que estaba a punto de ejecutarse.

El objetivo es que puedas revertir cambios sin perder el hilo de la sesión. Los checkpoints se almacenan en un directorio temporal dentro de ~/.gemini/tmp/ (Linux/macOS) o %USERPROFILE%\.gemini\tmp\ (Windows), organizados por hash del proyecto.

Elemento	Contenido
Archivos	Copia de los archivos antes de aplicar la herramienta (por ejemplo, write_file o run_shell_command).
Conversación	Historial del chat y prompts relevantes.
Metadata	Nombre del archivo, herramienta asociada y timestamp (YYYY-MM-DDTHH-MM-SSZ-archivo-tool).

El checkpointing trabaja junto a los checkpoints manuales (/chat save) pero se enfoca en proteger tu repositorio delante de operaciones automáticas.

7.2 Cómo activar y usar los checkpoints automáticos

En la configuración actual el checkpointing automático viene habilitado por defecto cuando el CLI detecta una herramienta sensible. Aun así, conviene conocer los controles disponibles:

• Activar/Desactivar a nivel global: en settings.json puedes ajustar general.checkpointing.enabled.
• Control por comandos: algunos flags como --checkpointing permiten reforzar el comportamiento en ejecuciones headless.
• Interacción durante la sesión: el CLI te indicará cuando ha creado un checkpoint antes de ejecutar la herramienta, mostrando la ruta generada.

Por ejemplo, si el agente va a modificar app.js, verás un mensaje similar a:

Checkpoint guardado en ~/.gemini/tmp/9a1f3c/app.js-write_file/

Los checkpoints están pensados como salvaguarda rápida; no reemplazan sistemas de versionado como Git. Aun así, son muy útiles para revertir cambios experimentales sin abandonar la sesión.

7.3 Restaurar un checkpoint

Para volver al estado previo, utiliza el comando /restore seguido del nombre del checkpoint. Puedes copiarlo de la ruta que apareció en el mensaje o consultar los directorios dentro de tmp.

/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

Al ejecutar /restore:

• Los archivos vuelven a su estado guardado.
• La conversación recupera el contexto del momento exacto en que se creó el checkpoint.
• El CLI muestra nuevamente el prompt original para que decidas si continúas, cancelas o ajustas la acción.

Si quieres listar los checkpoints disponibles antes de restaurar, recorre el directorio ~/.gemini/tmp/<hash>. Cada carpeta contiene subdirectorios con los nombres descriptores y los archivos de backup.

7.4 Escenarios prácticos y ventajas

• Refactor asistido: antes de dejar que Gemini CLI aplique un refactor grande, deja que genere el checkpoint y, si el resultado no convence, restaura al instante.
• Automatizaciones headless: en scripts que utilizan --prompt o pipelines CI/CD, habilita --checkpointing para mantener snapshots entre cada paso.
• Auditorías y revisiones: los checkpoints sirven como evidencia de cómo estaba el código antes de un ajuste sugerido por el agente.
• Trabajos colaborativos: si trabajas en un repositorio compartido, puedes documentar en tu wiki interna la ubicación de un checkpoint clave para que otra persona lo restaure y continúe el trabajo.

Ventajas clave:

• Reversión inmediata sin abandonar la sesión.
• Contexto completo (archivos + conversación) para retomar tareas.
• Integración nativa: no necesitas herramientas externas ni scripts personalizados.

7.5 Consejos y consideraciones

• Gestión de espacio: los checkpoints se acumulan en ~/.gemini/tmp. Borra manualmente los que ya no necesites para liberar espacio.
• Seguridad: si trabajas con información sensible, asegura el directorio de checkpoints o purga los snapshots luego de revisar los cambios.
• Compatibilidad: los checkpoints automáticos no sustituyen backups en repositorios binarios o bases de datos; aplícalos cuando los cambios recaen en archivos de texto.
• Complemento con Git: es buena práctica confirmar (o descartar) los cambios restaurados con un git status para entender su alcance antes de continuar.

Conclusión: el checkpointing de Gemini CLI actúa como un seguro instantáneo frente a cambios inesperados. Saber dónde se guardan los snapshots, cómo restaurarlos y cómo combinarlos con tus flujos de trabajo te permite experimentar con confianza.