Checkpointing - Gemini CLI

Checkpointing automatically saves a snapshot of your project’s state before any AI-powered file modifications. This lets you safely experiment with code changes, knowing you can instantly revert to the state before the tool was executed.

How It Works

When you approve a tool that modifies the file system (like write_file or replace), Gemini CLI automatically creates a checkpoint.

Tool Approval

You approve a file-modifying tool (e.g., write_file, replace).

Automatic Checkpoint

Before execution, the CLI creates a checkpoint containing:

Git snapshot: Complete project state in a shadow repository
Conversation history: Full chat history up to this point
Tool call: The specific tool about to be executed

Safe Execution

The tool executes with your files protected by the checkpoint.

Restore Anytime

Use /restore to revert files, conversation, and re-propose the tool call.

What’s Saved in a Checkpoint

Git Snapshot

Complete state of project files captured in a shadow Git repository at ~/.gemini/history/<project_hash>.Does not interfere with your project’s Git repository.

Conversation History

Entire conversation with the agent up to the checkpoint moment.

Tool Call

The specific tool call that was about to be executed, stored for re-proposal.

Enabling Checkpointing

Checkpointing is disabled by default and must be enabled in your settings.json file.

The --checkpointing command-line flag was removed in version 0.11.0. Use settings.json configuration only.

Configuration

Add to your settings.json:

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

User-Level
Project-Level
Using /settings

Edit ~/.gemini/settings.json to enable for all projects:

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

Edit <project>/.gemini/settings.json to enable for specific project:

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

Use the interactive settings editor:

/settings

Navigate to general.checkpointing.enabled and set to true.

Using the `/restore` Command

Once enabled, checkpoints are created automatically. Manage them with /restore.

List Available Checkpoints

Run without arguments to see all checkpoints:

/restore

Example Output:

Available checkpoints:

2025-06-22T10-00-00_000Z-app.js-write_file
2025-06-22T09-45-30_000Z-config.json-replace
2025-06-22T09-30-15_000Z-README.md-write_file

Checkpoint filenames contain:

Timestamp: When the checkpoint was created
File name: The file being modified
Tool name: The tool that was about to run

Restore a Specific Checkpoint

Use the checkpoint filename from the list:

/restore 2025-06-22T10-00-00_000Z-app.js-write_file

Files Restored

All project files revert to the captured snapshot state.

Conversation Restored

Chat history in the CLI returns to the checkpoint moment.

Tool Re-Proposed

The original tool call reappears, allowing you to:

Run it again
Modify it
Simply ignore it

Storage Locations

Checkpoint data is stored locally on your machine.

Git Snapshots

Shadow repository (does not interfere with your project Git):

~/.gemini/history/<project_hash>/

Checkpoint Metadata

Conversation history and tool calls:

Linux/macOS
Windows

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

C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\checkpoints\

Use Cases

Safe Experimentation

Try risky refactors or experimental changes knowing you can instantly revert.

Review Before Commit

Review AI-generated changes, restore if needed, then commit manually.

Compare Approaches

Restore to try alternative implementations of the same feature.

Undo Mistakes

Quickly recover from unwanted changes without manually reverting files.

Checkpointing vs. Session Management

Understand the difference between these two features:

Feature	Checkpointing	Session Management
Purpose	Snapshot before file modifications	Save conversation history
Trigger	Before tool execution (automatic)	Continuous (automatic)
What’s Saved	Files + conversation + tool call	Conversation only
Command	`/restore [checkpoint]`	`/resume` or `gemini --resume`
Storage	`checkpoints/` + `history/`	`chats/`
Use Case	Undo file changes	Resume work later

Checkpointing focuses on file safety while session management focuses on conversation continuity.

Manual Conversation Checkpoints

For manual conversation state saving (without file snapshots), use /chat commands:

/chat save my-checkpoint    # Save conversation state
/chat resume my-checkpoint  # Resume conversation state
/chat list                  # List manual checkpoints
/chat delete my-checkpoint  # Delete checkpoint

See Session Management for details.

Best Practices

Enable Per Project

Enable checkpointing in project-level settings.json for critical codebases while keeping it off for experimental projects.

Review Before Restore

List checkpoints with /restore to review the timestamp and file before restoring.

Clean Up Old Checkpoints

Periodically remove old checkpoints from ~/.gemini/tmp/<project_hash>/checkpoints/ to manage disk space.

Combine with Git

Use checkpointing for immediate safety and Git for long-term version control. Checkpoints complement, not replace, Git.

Troubleshooting

/restore command not available

Cause: Checkpointing is not enabled.Solution: Add "general": { "checkpointing": { "enabled": true } } to your settings.json.

No checkpoints listed

Cause: No file-modifying tools have been executed yet, or checkpoints were manually deleted.Solution: Approve a tool that modifies files (e.g., write_file) to create a checkpoint.

Restore didn't revert my files

Cause: Incorrect checkpoint selected, or files modified outside Gemini CLI.Solution:

Verify the checkpoint filename matches the change you want to undo
Check if files were modified by other tools/editors after the checkpoint
Use Git directly for changes made outside Gemini CLI

Shadow Git repository conflicts

Cause: Manual modifications to ~/.gemini/history/<project_hash>/.Solution: Do not manually edit the shadow repository. If corrupted, delete it and checkpointing will recreate it.

Disk space issues

Cause: Checkpoints accumulate over time for large projects.Solution:

Manually delete old checkpoints from ~/.gemini/tmp/<project_hash>/checkpoints/
Delete the shadow repository at ~/.gemini/history/<project_hash>/ if no longer needed
Consider enabling checkpointing only for specific projects

Advanced Usage

Checkpoint File Structure

Checkpoint files are JSON with the following structure:

{
  "timestamp": "2025-06-22T10:00:00.000Z",
  "file": "app.js",
  "tool": "write_file",
  "conversation": [...],
  "toolCall": {...},
  "gitCommit": "abc123..."
}

Shadow Repository

The shadow Git repository at ~/.gemini/history/<project_hash>/ contains:

Commits for each checkpoint
Complete file state snapshots
No branches (linear history)
Isolated from your project’s .git/

Do not manually modify the shadow repository. It’s managed entirely by Gemini CLI.

Session Management

Resume conversations with automatic history saving

Rewind

Navigate backward through conversation and file changes

Sandboxing

Isolated execution for additional safety

Next Steps

Configuration

Enable checkpointing in settings.json

Commands Overview

Learn about /restore and /rewind commands

Get Started

Core Concepts

CLI Usage

Tools & Extensions

Advanced

Resources

​How It Works

​What’s Saved in a Checkpoint

Git Snapshot

Conversation History

Tool Call

​Enabling Checkpointing

​Configuration

​Using the /restore Command

​List Available Checkpoints

​Restore a Specific Checkpoint

​Storage Locations

​Git Snapshots

​Checkpoint Metadata

​Use Cases

Safe Experimentation

Review Before Commit

Compare Approaches

Undo Mistakes

​Checkpointing vs. Session Management

​Manual Conversation Checkpoints

​Best Practices

Enable Per Project

Review Before Restore

Clean Up Old Checkpoints

Combine with Git

​Troubleshooting

​Advanced Usage

​Checkpoint File Structure

​Shadow Repository

​Related Features

Session Management

Rewind

Sandboxing

​Next Steps

Configuration

Commands Overview

Build docs developers (and LLMs) love

How It Works

What’s Saved in a Checkpoint

Enabling Checkpointing

Configuration

Using the `/restore` Command

List Available Checkpoints

Restore a Specific Checkpoint

Storage Locations

Git Snapshots

Checkpoint Metadata

Use Cases

Checkpointing vs. Session Management

Manual Conversation Checkpoints

Best Practices

Troubleshooting

Advanced Usage

Checkpoint File Structure

Shadow Repository

Related Features

Next Steps