How to Enable and Use Checkpointing in Gemini CLI

Checkpointing in Gemini CLI provides a safety net for your coding sessions. When Gemini makes changes to your files, you can create restore points that let you revert if something goes wrong. This guide covers everything you need to know about using checkpoints effectively.

Understanding Checkpoints

Checkpoints are snapshots of your project's modified files at a specific point in time. Unlike git commits, checkpoints are lightweight, session-aware, and designed specifically for AI-assisted coding workflows.

Key characteristics of checkpoints:

• File-level snapshots: Captures the content of files that have been modified during your session
• Named restore points: Each checkpoint has a name for easy identification
• Session persistence: Checkpoints persist across Gemini CLI sessions
• Non-destructive: Creating checkpoints doesn't affect your git history or working tree

Creating Checkpoints

Use the /checkpoint command to create a restore point. The command accepts an optional name to identify the checkpoint.

Basic Checkpoint Creation

# Create a checkpoint with auto-generated name
/checkpoint

# Create a named checkpoint
/checkpoint before-refactor

# Create a checkpoint with descriptive name
/checkpoint working-authentication

When to Create Checkpoints

Create checkpoints at strategic moments during your session:

• Before major refactoring: When Gemini is about to restructure significant code
• After successful changes: When a feature is working and you want to preserve that state
• Before experimental changes: When trying something that might not work
• At logical breakpoints: Between distinct tasks or features

# Example workflow
You: "Add user authentication to this Express app"
Gemini: [makes changes to auth routes]
You: /checkpoint auth-routes-complete

You: "Now add OAuth support"
Gemini: [makes OAuth changes]
# If OAuth changes break something, you can restore to auth-routes-complete

Listing Available Checkpoints

View all your checkpoints with the /checkpoints command:

/checkpoints

This displays:

• Checkpoint name
• Creation timestamp
• Number of files captured
• Files included in each checkpoint

Restoring from Checkpoints

The /restore command reverts your files to a previous checkpoint state.

Basic Restore

# Restore to a named checkpoint
/restore before-refactor

# Restore to the most recent checkpoint
/restore

What Happens During Restore

When you restore a checkpoint:

1. Only modified files are affected: Files unchanged since the checkpoint remain untouched
2. Current state is preserved: Gemini creates an automatic checkpoint of the current state before restoring
3. Selective restoration: You can restore specific files from a checkpoint

Important Considerations

• Restoring does not affect untracked files that weren't part of the checkpoint
• Your git working tree changes with the restore
• Git sees the restored files as modified (unstaged)

Checkpoint vs Git: When to Use Each

Both checkpointing and git serve different purposes in your workflow:

Recommended Workflow

1. Start session: Create initial checkpoint
2. Major milestones: Create named checkpoints AND git commits
3. Experimentation: Use checkpoints freely
4. End session: Commit working changes to git, clean up checkpoints

# Combined workflow example
/checkpoint session-start
# ... Gemini makes changes ...
/checkpoint feature-complete
git add -A && git commit -m "Add user authentication"

Automatic Checkpoint Creation

Gemini CLI can automatically create checkpoints at certain points:

Auto-checkpoint Triggers

• Before file modifications: When Gemini is about to write to files
• Session boundaries: At session start/end
• Before destructive operations: When changes might break things

Configuring Auto-checkpoints

Auto-checkpointing behavior can be configured in ~/.gemini/settings.json:

{
  "checkpointing": {
    "autoCheckpoint": true,
    "autoCheckpointInterval": 10,
    "maxAutoCheckpoints": 5
  }
}

Checkpoint Storage and Cleanup

Checkpoints are stored locally and can accumulate over time.

Storage Location

~/.gemini/
└── checkpoints/
    └── <project-hash>/
        ├── before-refactor/
        │   ├── manifest.json
        │   └── files/
        └── working-auth/
            ├── manifest.json
            └── files/

Cleaning Up Checkpoints

# Delete a specific checkpoint
/checkpoint delete before-refactor

# Clear all checkpoints for current project
/checkpoint clear

# Clear checkpoints older than 7 days
/checkpoint clear --older-than 7d

Best Practices

Do

• Name checkpoints descriptively: Use names like pre-database-changes not cp1
• Create checkpoints before risky operations: Better safe than sorry
• Combine with git: Use checkpoints for micro-iterations, git for milestones
• Clean up regularly: Remove checkpoints you no longer need

Avoid

• Relying solely on checkpoints: They're not a replacement for git
• Creating too many checkpoints: They consume disk space
• Ignoring checkpoint names: You'll forget what checkpoint-1 was

Limitations and Considerations

Be aware of these limitations:

• Local only: Checkpoints don't sync across machines
• No diff viewing: You can't preview differences between checkpoints
• Project-scoped: Checkpoints are tied to specific project directories
• No partial file restore: You restore entire files, not specific lines

Additional Resources

• Gemini CLI GitHub Repository
• How to Install Google Gemini CLI
• Where Configuration Files Are Stored

Need help optimizing your AI-assisted development workflow? Contact us to discuss integrating AI tools into your team's workflow.