AI coding agents can accelerate test maintenance, but a plausible edit is not necessarily a safe edit. A changed assertion may hide a regression, a shared fixture may affect dozens of cases, and a cleanup can silently delete the evidence you needed. Gemini CLI checkpointing for QA gives testers a practical recovery point before approved AI tools modify project files.

This tutorial builds a small recovery drill around test code. You will enable checkpointing, make a controlled AI edit, inspect the available snapshots, restore the project, rerun deterministic tests, and document where the safety boundary ends. The goal is not to trust an undo button blindly. It is to test recovery with the same discipline you apply to a release.

What Gemini CLI checkpointing actually saves

According to the official Gemini CLI checkpointing documentation, the feature is disabled by default. When enabled, Gemini CLI creates a checkpoint before an approved file-modifying tool, such as write_file or replace, executes.

Each checkpoint contains three useful pieces of state:

  • A project snapshot stored as a commit in a separate shadow Git repository under ~/.gemini/history/<project_hash>.
  • The conversation history up to the edit.
  • The tool call that was about to run.

The shadow repository does not replace or modify your normal project repository. Checkpoint metadata for the conversation and tool call is stored locally, typically under ~/.gemini/tmp/<project_hash>/checkpoints. Restoring a checkpoint returns project files and conversation history to the captured state and re-proposes the original tool call.

Set up a disposable QA recovery lab

Use a small repository created only for this exercise. Include one production-like function, one test file, and a fixture. Commit a known-good baseline in your normal Git repository even though Gemini CLI uses a separate shadow repository for checkpoints.

qa-checkpoint-lab/
  src/price.py
  tests/test_price.py
  tests/data/prices.json
  README.md

Create three deterministic checks: a happy path, a boundary value, and an invalid-input case. Run them and record the baseline result, test count, commit hash, and checksum for each file. This gives you an oracle for judging whether recovery is complete.

If the project came from an unfamiliar source, consider enabling Trusted Folders first. Gemini CLI documents this control as disabled by default. When enabled, an untrusted folder runs in a restricted safe mode until you explicitly trust it. Review discovered commands, MCP servers, hooks, skills, and settings before granting trust.

Enable checkpointing in settings.json

Add the documented configuration to your Gemini CLI settings.json:

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

Restart or reopen the CLI session if needed, then confirm the setting is active in the lab project. Do not depend on old command-line examples: current official documentation says checkpointing is configured through settings.json.

Run the first controlled edit

Ask Gemini CLI for a narrow, observable change. A good prompt is:

Add a parameterized test for zero, one, and two decimal places in tests/test_price.py. Do not change production code or existing assertions. Show the proposed diff and wait for approval before editing.

Before approval, capture the proposed scope. After approval, confirm that only the expected file changed. Then run the same deterministic test command used for the baseline. Record the result even when every test passes; passing tests do not prove that restoration works.

List and restore a checkpoint

Run the following slash command inside Gemini CLI:

/restore

The CLI lists checkpoints for the current project. Names typically include a timestamp, affected file, and tool name. Copy the exact checkpoint name, then restore it:

/restore <checkpoint_file>

Now verify all three recovery dimensions:

  1. Files: compare checksums and Git status with the baseline.
  2. Conversation: confirm that the chat returned to the pre-edit point.
  3. Intent: confirm that the original tool request is proposed again but has not silently executed.

Rerun the deterministic test suite. A valid recovery result requires both the expected file state and the expected test result. Save terminal output, checkpoint name, before-and-after checksums, and the final Git diff as evidence.

Checkpoint test matrix for QA teams

Scenario Expected result Evidence
Single approved AI edit A checkpoint appears before the change; restore returns the baseline Checkpoint list, diff, test output
Two sequential AI edits Each checkpoint maps to the correct pre-edit state Ordered names, checksums at each state
Edit in a nested test folder The full project snapshot restores consistently Repository-wide status and tests
Manual edit after an AI edit Observed behavior is documented before relying on recovery Manual marker, restored diff, notes
Shell-generated file change Do not assume chat rewind will undo it File checksum and command log
Failed or interrupted restore Team stops, preserves evidence, and recovers through Git or backup Error output and recovery record
Untrusted project folder Project configuration stays restricted until reviewed and trusted Trust dialog and discovered items

Include untracked files, renamed files, deleted fixtures, large binary artifacts, and simultaneous work in your local compatibility testing. The documentation describes the normal workflow; your operating system, filesystem, repository size, and team conventions still need direct validation.

Choose /restore or /rewind deliberately

/restore is checkpoint-oriented: it selects a saved pre-tool snapshot and restores files, conversation history, and the pending tool call together. The official rewind documentation describes a different interactive workflow. With /rewind or two Escape key presses, you select a prior interaction and may rewind the conversation, revert AI-made code changes, or do both.

This distinction matters in test investigations. Rewinding only the conversation means the model loses the removed context while the files stay changed. Reverting only code means the conversation still refers to a state that no longer exists, so you should tell the model what changed. Gemini CLI also states that rewind does not undo manual edits or changes triggered through the shell tool. Test these boundaries instead of assuming every mutation participates in the same recovery path.

Safety controls checkpoints do not replace

  • Normal Git history: use branches and commits for durable, reviewable team recovery.
  • CI: rerun unit, API, UI, security, and static checks that match the edit’s risk.
  • Backups: keep recoverable copies of important fixtures, datasets, and generated evidence.
  • Peer review: inspect assertions for weakened expectations, removed coverage, and false positives.
  • Access control: use trusted folders, least privilege, sanitized test data, and isolated environments.
  • Human decisions: keep defect closure, merge, and release approval with accountable reviewers.

A checkpoint is a local recovery mechanism, not proof that the edit was correct. Treat it as one layer in a tested rollback strategy.

Definition of done for the recovery drill

Your Gemini CLI checkpointing exercise is complete when a tester can reproduce the baseline, identify the right checkpoint, restore the expected files and conversation, rerun tests successfully, and explain what the mechanism does not cover. Store the evidence beside the test plan and repeat the drill after meaningful configuration or workflow changes.

For implementation details and current behavior, use the official Gemini CLI repository and documentation rather than copied setup snippets. The best recovery feature is one your QA team has already tested before a real incident.