gemini-checkpoint-management
Central authority for Gemini CLI Checkpointing. Covers git-based file snapshots, automatic state saving, /restore command, and rollback. Use when enabling checkpointing, restoring previous states, undoing changes, or planning experimental workflows with Gemini. Delegates 100% to gemini-cli-docs for official documentation.
When & Why to Use This Skill
The Gemini Checkpoint Management skill provides a robust safety net for developers using Gemini CLI by managing git-based file snapshots and session states. It automates the creation of checkpoints before file modifications, allowing for seamless rollbacks and state restoration, which is essential for experimental coding workflows and risk-free refactoring.
Use Cases
- Experimental Refactoring: Safely perform large-scale code changes knowing you can instantly revert to a previous state if the logic fails.
- Session Recovery: Use the /restore command to browse and return to specific points in your development history after unexpected tool outputs.
- State Management: Configure and verify automatic checkpointing settings to ensure every file modification is backed up in a local shadow repository.
- Workflow Auditing: Track the sequence of tool calls and file changes by listing timestamped checkpoints to understand the project's evolution.
| name | gemini-checkpoint-management |
|---|---|
| description | Central authority for Gemini CLI Checkpointing. Covers git-based file snapshots, automatic state saving, /restore command, and rollback. Use when enabling checkpointing, restoring previous states, undoing changes, or planning experimental workflows with Gemini. Delegates 100% to gemini-cli-docs for official documentation. |
| allowed-tools | Read, Glob, Grep, Skill |
Gemini Checkpoint Management
MANDATORY: Invoke gemini-cli-docs First
STOP - Before providing ANY response about Gemini checkpointing:
- INVOKE
gemini-cli-docsskill- 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
/restorecommand - 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