Gemini CLIのCheckpointing機能を使ってみた

1.Checkpointing機能とは何か

Checkpointing とは、AI への指示とそれに伴うツール呼び出し処理を1つのチェックポイントとして自動保存してくれる機能です。この機能を有効にすると、Gemini CLI への指示から処理までがローカルのチェックポイントファイルに記録されます。
このチェックポイントファイルを指定する形で /restore コマンドを実行すると、そこに記録されている直前の状態に切り戻せると共にツール呼び出しが実行されます。

説明すると上記の通りなのですが、使ってみた方が使用イメージがわくかと思いますので、実際に Gemini CLI で Checkpointing を有効化し操作してみた結果をご紹介します。

2.Checkpointing機能を有効化する

まず Gemini CLI の設定ファイル（~/.gemini/settings.json）の general セクションに Checkpointing を有効化する設定を記入します。

{
  "security": {
    〜〜〜
      〜〜省略〜〜
    〜〜〜
  },
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

これで有効化は完了なのですが、注意事項として Git のバージョン確認をお勧めします。
以下の通り、Checkpointing のドキュメントの How it works の箇所に Git を使用している旨の記述がございます。

＜日本語訳＞Git スナップショット:コミットは、ホームディレクトリ ( ~/.gemini/history/) にある特別なシャドー Git リポジトリに作成されます。このスナップショットは、その時点におけるプロジェクトファイルの完全な状態をキャプチャします。これは、あなた自身のプロジェクトの Git リポジトリに影響を与えることはありません。

もし使用している Git のバージョンが2.28未満の場合、 Gemini CLI を立ち上げると以下のエラーが発生します。

Error: Failed to initialize checkpointing: error: unknown option `initial-branch=main`

ですので、あらかじめ Git はバージョン2.28以上を使用していることのご確認をお勧めします。

Checkpointing を有効化したら Gemini CLI を立ち上げます。
今回使用している Gemini CLI と Git のバージョンは以下です。

Gemini CLIのバージョン（ gemini --version ）：0.21.3
Git のバージョン（ git --version ）： 2.52.0

Gemini CLI を立ち上げると以下のディレクトリが自動作成されます。

~/.gemini/history/hash/
~/.gemini/tmp/hash/checkpoints/

tmp フォルダの checkpoints フォルダ配下にチェックポイントファイルが作成され、このファイルを /restore コマンドで指定する形になります。
では実際に Gemini CLI でチェックポイントファイルの作成、/restore コマンドを実行してみます。

3.Checkpointing機能を使ってみる

では、実際に Checkpointing がどう動作するか、フォルダの中身を見ながら進めていきます。
あらかじめ作成しておいた、/Users/<名前>/Documents/XYZ案件で Gemini CLI を立ち上げます。
このフォルダの中身は空です。

Gemini CLI を立ち上げました。

Gemini CLI 立ち上げると、~/.gemini/tmp/ にハッシュ名のフォルダが作成されます。

~/.gemini/tmp/7ed01bb682f3c9689deff466a071c119043b3629093bef2e0ba0a26f98c8584c

こちらのハッシュ名フォルダには chats フォルダと json ファイルが作成されていました。

7ed01bb682f3c9689deff466a071c119043b3629093bef2e0ba0a26f98c8584c $ ls -la
〜〜省略〜〜
drwxr-xr-x  〜〜省略〜〜 chats
-rw-r--r--  〜〜省略〜〜 logs.json

では、続いて Gemini CLI でプロンプトを実行します。

プロンプトの内容はこちらです。

セキュリティグループ.md を作成してください。
中身は設定の詳細設計です。
セキュリティグループの名前は ec2-sg
インバウンドルール：ポート 443 の IP 0.0.0.0/0
アウトバウンドルール：デフォルト

AI がツール実行するにあたり、ユーザーに承認を求める選択肢が表示されています。

ここで~/.gemini/tmp/ の中身を見てみると新たに checkpoints フォルダが作成されていました。

7ed01bb682f3c9689deff466a071c119043b3629093bef2e0ba0a26f98c8584c $ ls -la
〜〜省略〜〜
drwxr-xr-x  〜〜省略〜〜 chats
drwxr-xr-x  〜〜省略〜〜 checkpoints
-rw-r--r--  〜〜省略〜〜 logs.json

checkpoints フォルダの中身を見ると json ファイルが作成されています。

$ ls
2025-12-〜〜省略〜〜_035Z-セキュリティグループ.md-write_file.json

ファイルの中身については内容が長いため省略していますが、会話履歴、AI の思考、実行内容、Git コミットハッシュが記録されています。
この checkpoints フォルダの json ファイルの内容が checkpoints における復帰ポイントになります。

$ cat 2025-12-〜〜省略〜〜_035Z-セキュリティグループ.md-write_file.json
{
  "history": [
    {
      "type": "user",
      "text": "セキュリティグループ.md を作成してください。\n中身は設定の詳細設計です。\nセキュリティグループの名前は ec2-sg\nインバウンドルール：ポート 443 の IP 0.0.0.0/0\nアウトバウンドルール：デフォルト",
      "id": 1766236378872
    }
  ],
  "clientHistory": [
    {
      "role": "user",
      "parts": [
        {
          "text": "This is the Gemini CLI. We are setting up the context for our chat.〜〜省略〜〜
〜〜省略〜〜
{
      "role": "user",
      "parts": [
        {
          "text": "セキュリティグループ.md を作成してください。\n中身は設定の詳細設計です〜〜省略〜〜
〜〜省略〜〜
{
      "role": "model",
      "parts": [
        {
          "thoughtSignature": "C〜〜省略〜〜
〜〜省略〜〜
  "toolCall": {
    "name": "write_file",
    "args": {
      "content": "# セキュリティグループ設計\n\n## セキュリティグループ名\nec2-sg\n\n## インバウンドルール\n| タイプ    | プロトコル | ポート範囲 | ソース      | 説明     |\n| :---------- | :--------- | :--------- | :---------- | :------- |\n| HTTPS       | TCP        | 443        | 0.0.0.0/0   | どこからでもHTTPSアクセスを許可 |\n\n## アウトバウンドルール\n| タイプ    | プロトコル | ポート範囲 | 宛先      | 説明     |\n| :---------- | :--------- | :--------- | :---------- | :------- |\n| すべてのトラフィック | すべて     | すべて     | 0.0.0.0/0 | すべてのトラフィックをどこへでも許可 (デフォルト) |",
      "file_path": "セキュリティグループ.md"
    }
  },
  "commitHash": "7eb1dea292a845fc14dc60086e20b0cc1c182c6b",
  "messageId": "c08a1ed7-06eb-4736-b857-18c17b88400e########0"
}

ターミナルに戻り、1.Yes, allow one を選択します。

指定通りのマークダウンファイルが作成されました。

$ ls
セキュリティグループ.md
$ cat セキュリティグループ.md 
# セキュリティグループ設計

## セキュリティグループ名
ec2-sg

## インバウンドルール
| タイプ    | プロトコル | ポート範囲 | ソース      | 説明     |
| :---------- | :--------- | :--------- | :---------- | :------- |
| HTTPS       | TCP        | 443        | 0.0.0.0/0   | どこからでもHTTPSアクセスを許可 |

## アウトバウンドルール
| タイプ    | プロトコル | ポート範囲 | 宛先      | 説明     |
| :---------- | :--------- | :--------- | :---------- | :------- |
| すべてのトラフィック | すべて     | すべて     | 0.0.0.0/0 | すべてのトラフィックをどこへでも許可 (デフォルト) |

続いて2つ目のプロンプトを実行します。
内容は以下です。

インバウンドルールにポート 80 の IP 0.0.0.0/0 を追加してください

ツール実行の承認が出ています。

checkpoints フォルダの中身を見ると新たな json ファイルが作成されています。

$ ls
2025-12-〜〜省略〜〜_035Z-セキュリティグループ.md-write_file.json
2025-12-〜〜省略〜〜_097Z-セキュリティグループ.md-replace.json

新たに作成された2025-12-〜〜省略〜〜_097Z-セキュリティグループ.md-replace.json の中身は以下です。
こちらも内容が長いので省略しております。

{
  "history": [
    {
      "type": "user",
      "text": "セキュリティグループ.md を作成してください。\n中身は設定の詳細設計です。\nセキュリティグループの名前は ec2-sg\nインバウンドルール：ポート 443 の IP 0.0.0.0/0\nアウトバウンドルール：デフォルト",
      "id": 1766236378872
    },
    {
      "type": "tool_group",
      "tools": [
        {
          "callId": "write_file-1766236407884-0cbfa0b353d3e",
          "name": "WriteFile",
          "description": "Writing to セキュリティグループ.md",
          "renderOutputAsMarkdown": true,
          "status": "Success",
          "resultDisplay": {
            "fileDiff": "Index: セキュリティグループ.md
〜〜省略〜〜
{
      "type": "user",
      "text": "インバウンドルールにポート 80 の IP 0.0.0.0/0 を追加してください",
      "id": 1766237176291
    },
    {
      "type": "gemini",
      "text": "OK. I will add an inbound rule for port 80 from 0.0.0.0/0 to the `セキュリティグループ.md` file.",
      "id": 1766237176292
    },
{
      "type": "tool_group",
      "tools": [
        {
          "callId": "read_file-1766237212729-36bb1a08f093e",
          "name": "ReadFile",
          "description": "セキュリティグループ.md",
          "renderOutputAsMarkdown": true,
          "status": "Success",
          "resultDisplay": ""
        }
      ],
      "id": 1766237212750
    }
  ],
  "clientHistory": [
    {
      "role": "user",
      "parts": [
        {
          "text": "This is the Gemini CLI. We are setting up the context for our chat.〜〜省略〜〜
〜〜省略〜〜
"toolCall": {
    "name": "replace",
    "args": {
      "file_path":〜〜省略〜〜
〜〜省略〜〜
  },
  "commitHash": "086f65f867dcc87103397b4e664c963366ef24fc",
  "messageId": "c08a1ed7-06eb-4736-b857-18c17b88400e########1"
}

1.Yes, allow one を選択します。

指定通り、インバウンドルールにポート80が追加されました。

$ cat セキュリティグループ.md 
# セキュリティグループ設計

## セキュリティグループ名
ec2-sg

## インバウンドルール
| タイプ    | プロトコル | ポート範囲 | ソース      | 説明     |
| :---------- | :--------- | :--------- | :---------- | :------- |
| HTTPS       | TCP        | 443        | 0.0.0.0/0   | どこからでもHTTPSアクセスを許可 |
| HTTP        | TCP        | 80         | 0.0.0.0/0   | どこからでもHTTPアクセスを許可    |

## アウトバウンドルール
| タイプ    | プロトコル | ポート範囲 | 宛先      | 説明     |
| :---------- | :--------- | :--------- | :---------- | :------- |
| すべてのトラフィック | すべて     | すべて     | 0.0.0.0/0 | すべてのトラフィックをどこへでも許可 (デフォルト) |

次に /restore コマンドを実行してみます。
利用可能なチェックポイントが2つ表示されており、checkpoints フォルダに作成されたチェックポイントファイルが表示されています。

> /restore
2025-12-〜〜省略〜〜_035Z-セキュリティグループ.md-write_file
2025-12-〜〜省略〜〜_097Z-セキュリティグループ.md-replace

最初に作成されたチェックポイントファイルを選択し実行します。
最初のプロンプトの指示は md ファイルの作成だったので、まずは md ファイルが削除され、空ディレクトリ状態となり、続いて最初に実行した md ファイルの作成依頼指示が実行されるはずです。

> /restore 2025-12-〜〜省略〜〜_035Z-セキュリティグループ.md-write_file

md ファイルが削除されています。

続いてセキュリティグループ.md の作成承認をします。

下記の通り、セキュリティグループ.md が作成されました。
中身についても80ポートを追加する前の指示なので、インバウンドルールは443ポートのみで期待通りの結果となっています。

## md ファイルが削除されたので ls コマンドを実行しても md ファイルは表示されない。 
$ ls
XYZ案件 $

## 1.Yes, allow one 選択後に ls コマンドを実行。md ファイルが作成されている。
$ ls
セキュリティグループ.md

## md ファイルを見ると2つ目の指示実行前の状態をリストアしたのでポート80の記載は無し。
$ cat セキュリティグループ.md 
# セキュリティグループ設計

## セキュリティグループ名
ec2-sg

## インバウンドルール
| タイプ    | プロトコル | ポート範囲 | ソース      | 説明     |
| :---------- | :--------- | :--------- | :---------- | :------- |
| HTTPS       | TCP        | 443        | 0.0.0.0/0   | どこからでもHTTPSアクセスを許可 |

## アウトバウンドルール
| タイプ    | プロトコル | ポート範囲 | 宛先      | 説明     |
| :---------- | :--------- | :--------- | :---------- | :------- |
| すべてのトラフィック | すべて     | すべて     | 0.0.0.0/0 | すべてのトラフィックをどこへでも許可 (デフォルト) |

ちなみに、この続きで Gemini CLI に「私はまだあなたにポート80を追加して欲しいという依頼をしていないですよね？」と聞いてみると、その通りですとの回答がありました。

このことから会話の履歴についてもポート80を追加する前の状態に切り戻っていることがわかります。

4.終わりに

以上が実際に Checkpointing 機能を操作してみた結果です。
AI を使ったドキュメント作成やコーディングを行う際、人間の指示に対してAI が想定通りのアウトプットをしてくれない場面に出くわすことがあるかと思います。
その際、この Checkpointing を使えば、そのアウトプットが行われる前の状態に切り戻すことができ、改めて AI に最適な指示を出し、想定通りのアウトプットを引き出すことができるかと思います。
このブログが AI との協働におけるより良いアウトプットを得るための一助になれば幸いです。

Gemini CLIのCheckpointing機能を使ってみた

目次

1.Checkpointing機能とは何か

2.Checkpointing機能を有効化する

3.Checkpointing機能を使ってみる

4.終わりに

生成 AI でスライド作成！Gemini 3 と NotebookLM のスライド生成を実際に試してみた

Figma Makeとは？徹底解説します！

WindowsServer上に作成したローカルユーザーのパスワード有効期限管理パターンとその適用手順をまとめてみる

Googleカレンダーの「日本の祝日」の仕様が変更された件

2025年度版！AWS資格取得の順番について！

Gemini CLIのCheckpointing機能を使ってみた

目次

1.Checkpointing機能とは何か

2.Checkpointing機能を有効化する

3.Checkpointing機能を使ってみる

4.終わりに

関連記事Related Articles

Gemini CLIをVertex AIで安全に利用する

Obsidianにターミナルを統合してGemini CLIを組み込む

【Google Cloud Next Tokyo 2025】Gemini CLI を使いこなす！

Kali LinuxとGemini CLIで脆弱性管理してみた

Gemini CLI Extensionsを使ってmonday.comを操作してみた