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.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

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.
namegemini-checkpoint-management
descriptionCentral 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-toolsRead, Glob, Grep, Skill

Gemini Checkpoint Management

MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini checkpointing:

  1. INVOKE gemini-cli-docs skill
  2. QUERY for the specific checkpointing topic
  3. 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:

  1. Git Snapshot: Shadow repo at ~/.gemini/history/<project_hash>
  2. Conversation History: Complete session state
  3. 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?

  1. Enable checkpointing -> Query gemini-cli-docs: "checkpointing enabled settings"
  2. List checkpoints -> Use /restore command
  3. Restore state -> Use /restore <checkpoint_name>
  4. Find storage -> Query gemini-cli-docs: "checkpoint storage ~/.gemini/history"
  5. Understand workflow -> Query gemini-cli-docs: "checkpointing workflow"

Best Practices

  1. Enable for experiments: Always enable when doing risky refactors
  2. Note checkpoint names: Before major changes, list existing checkpoints
  3. Test after restore: Verify state after restoring
  4. 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