Gemini Checkpoint Management

MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini checkpointing:

• INVOKE gemini-cli-docs skill

• QUERY for the specific checkpointing topic

• BASE responses EXCLUSIVELY on official documentation loaded

Overview

Meta-skill for managing Gemini CLI's checkpointing system. Checkpointing creates automatic snapshots before file modifications, enabling instant rollback.

When to Use This Skill

Keywords: checkpoint, rollback, restore, undo, snapshot, revert, experiment, checkpointing, /restore

Use this skill when:

• Enabling or configuring checkpointing

• Listing available checkpoints

• Restoring to a previous state

• Understanding checkpoint storage

• Planning experimental workflows

How Checkpointing Works

When enabled, before any file modification Gemini creates:

• Git Snapshot: Shadow repo at ~/.gemini/history/<project_hash>

• Conversation History: Complete session state

• Pending Tool Call: The operation about to execute

Checkpoints are stored locally and don't interfere with your project's Git repository.

Configuration

Enable Checkpointing

Add to settings.json :

{ "general": { "checkpointing": { "enabled": true } } }

Verify Configuration

cat ~/.gemini/settings.json | jq '.general.checkpointing'

Commands

List Checkpoints

/restore

Shows available checkpoint files for the current project.

Restore Checkpoint

/restore <checkpoint_file>

Restores files and conversation to the checkpoint state.

Checkpoint Naming

Format: {timestamp}-{filename}-{tool_name}

Example: 2025-06-22T10-00-00_000Z-my-file.txt-write_file

Storage Locations

Data Location

Git snapshots ~/.gemini/history/<project_hash>

Checkpoint metadata ~/.gemini/tmp/<project_hash>/checkpoints

Keyword Registry (Delegates to gemini-cli-docs)

Topic Query Keywords

Enable checkpointing enabled , enable checkpointing settings

Commands /restore command , list checkpoints , restore checkpoint

Storage checkpoint storage , ~/.gemini/history , snapshot location

Workflow checkpointing workflow , automatic snapshots

Quick Decision Tree

What do you want to do?

• Enable checkpointing -> Query gemini-cli-docs: "checkpointing enabled settings"

• List checkpoints -> Use /restore command

• Restore state -> Use /restore <checkpoint_name>

• Find storage -> Query gemini-cli-docs: "checkpoint storage ~/.gemini/history"

• Understand workflow -> Query gemini-cli-docs: "checkpointing workflow"

Best Practices

• Enable for experiments: Always enable when doing risky refactors

• Note checkpoint names: Before major changes, list existing checkpoints

• Test after restore: Verify state after restoring

• Clean up periodically: Old checkpoints consume disk space

Verification Checkpoint

• Did I invoke gemini-cli-docs skill?

• Did official documentation load?

• Is my response based EXCLUSIVELY on official docs?

Test Scenarios

Scenario 1: Direct Activation

Query: "Use the gemini-checkpoint-management skill to enable checkpointing" Expected Behavior:

• Skill activates on keyword "checkpoint"

• Delegates to gemini-cli-docs for official documentation Success Criteria: User receives accurate checkpointing configuration steps

Scenario 2: Keyword Activation

Query: "How do I rollback changes in Gemini CLI?" Expected Behavior:

• Skill activates on keywords "rollback", "restore"

• Provides /restore command usage Success Criteria: Response includes command syntax and checkpoint listing

Scenario 3: Troubleshooting

Query: "Where are Gemini checkpoints stored?" Expected Behavior:

• Skill activates on "checkpoint storage"

• Provides ~/.gemini/history path information Success Criteria: User understands checkpoint storage structure

References

Query gemini-cli-docs for official documentation on:

• "checkpointing"

• "/restore command"

• "checkpoint storage"

Version History

• v1.1.0 (2025-11-30): Added Test Scenarios section

• v1.0.0 (2025-11-25): Initial release