Gemini CLI Guide: Checkpoints, Restore, and Safe Recovery

InYourLeague Research · 2026-08-27

Answer in brief

Gemini CLI checkpointing is an opt-in recovery feature that saves local recovery data before an approved file-modifying tool runs. Restoring returns the captured project files and conversation to that point, then re-proposes the recorded tool call without automatically running it.

Key facts at a glance

Failure modes and verification

FAQ

Is checkpointing enabled by default in Gemini CLI?

No. general.checkpointing.enabled defaults to false. Use gemini --checkpointing for the current session or enable the setting in an applicable settings.json, as described in the configuration documentation.

Exactly when is a checkpoint created?

A checkpoint is created after you approve an AI-powered tool that modifies the file system and before that tool performs the modification. The documentation gives write_file and replace as examples.

Where does Gemini CLI store checkpoint data?

Project-file snapshots are stored in the shadow Git repository at ~/.gemini/history/<project_hash>. Conversation history and tool calls are stored as JSON checkpoint data, typically under ~/.gemini/tmp/<project_hash>/checkpoints.

What does /restore <checkpoint_file> restore?

It restores every project file represented by the snapshot and the saved conversation. It then re-proposes the original tool call so you can run, modify, or ignore it.

Does restoration automatically rerun the original tool call?

No. The original call is re-proposed after restoration but is not automatically executed.

Does a checkpoint back up Gemini CLI extensions?

The supplied official pages provide no extension-specific backup or restoration guarantee. They do not establish that extension installations, out-of-project settings, remote resources, or other extension-managed external state are captured.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

Core answer

Gemini CLI checkpointing is an opt-in recovery feature. Once enabled, it creates a checkpoint after you approve an AI-powered tool that will modify the file system and before the tool makes the change. A later /restore returns the captured project files and conversation to their earlier state. It then re-proposes the recorded tool call so you can run, modify, or ignore it.

Checkpointing is disabled by default. Enable it for the current session with gemini --checkpointing, or enable it persistently through general.checkpointing.enabled in an applicable settings.json file. The behavior is documented in the official checkpointing and configuration pages.

What a checkpoint captures

The checkpointing documentation identifies three captured components:

The shadow repository is separate from the project’s own Git repository, so checkpoint creation does not add commits to the project repository. The documentation describes all checkpoint data as local to the machine: the shadow repository holds the project snapshot, while the project-specific temporary directory holds the conversation and tool-call records.

Enabling checkpointing

For one session, start the CLI with:

gemini --checkpointing

For persistent use, add the following setting to the appropriate settings.json:

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

Use ~/.gemini/settings.json to configure the current user or .gemini/settings.json in the project root to configure only that project. Settings follow a precedence order: project settings override user settings, and system override settings, environment variables, and command-line arguments can take precedence over both. If observed behavior differs from one settings file, inspect the higher-precedence layers.

Listing and restoring checkpoints

Run /restore without an argument to list checkpoints saved for the current project. Their names typically combine a timestamp, the affected file name, and the tool that was about to run. Restore a listed checkpoint with:

/restore <checkpoint_file>

Restoration is not limited to the file named in the checkpoint. It reverts every project file represented by the snapshot and restores the saved conversation. The original tool call then reappears, but /restore does not automatically execute it. Review the re-proposed call before deciding whether to run, edit, or ignore it.

Approval and extension boundaries

The documented creation boundary is approval of an AI-powered tool that modifies the file system, such as write_file or replace. The two supplied official pages do not say that read-only tools, unapproved proposals, every CLI command, or every tool invocation create checkpoints. Enabling checkpointing therefore does not provide a recovery point for every action.

Those pages also define no extension-specific checkpoint or restoration policy. They do not establish that extension installation state, settings outside the captured project, remote resources, or other extension-managed external state are included. Treat checkpointing as recovery for the documented project files, conversation history, and pending modifying tool call—not as a complete extension backup. Preserve extension-managed or external state separately when it matters.

Safe restore workflow

• Verify that checkpointing was enabled before the modifying tool was approved.
• Use /restore to list checkpoints for the current project and copy the exact checkpoint name.
• Account for the fact that restoration affects the complete captured project state.
• After restoration, inspect the conversation and re-proposed tool call before approving another change.

Model availability note: The official source does not specify a selectable model ID.