Was this page helpful?
ファイルチェックポイントは、エージェントセッション中にWrite、Edit、NotebookEditツールを通じて行われたファイル変更を追跡し、任意の以前の状態にファイルを巻き戻すことができます。試してみたいですか?インタラクティブな例にジャンプしてください。
チェックポイントを使用すると、以下のことができます:
Write、Edit、NotebookEditツールを通じて行われた変更のみが追跡されます。Bashコマンド(echo > file.txtやsed -iなど)を通じて行われた変更は、チェックポイントシステムによってキャプチャされません。
ファイルチェックポイントを有効にすると、SDKはWrite、Edit、またはNotebookEditツールを通じてファイルを変更する前にバックアップを作成します。レスポンスストリーム内のユーザーメッセージには、復元ポイントとして使用できるチェックポイントUUIDが含まれます。
チェックポイントは、エージェントがファイルを変更するために使用する以下の組み込みツールで動作します:
| ツール | 説明 |
|---|---|
| Write | 新しいファイルを作成するか、既存のファイルを新しい内容で上書きする |
| Edit | 既存のファイルの特定の部分に対して的を絞った編集を行う |
| NotebookEdit | Jupyterノートブック(.ipynbファイル)のセルを変更する |
ファイルの巻き戻しは、ディスク上のファイルを以前の状態に復元します。会話自体は巻き戻しません。rewindFiles()(TypeScript)またはrewind_files()(Python)を呼び出した後も、会話履歴とコンテキストはそのまま残ります。
チェックポイントシステムは以下を追跡します:
チェックポイントに巻き戻すと、作成されたファイルは削除され、変更されたファイルはその時点の内容に復元されます。
ファイルチェックポイントを使用するには、オプションで有効にし、レスポンスストリームからチェックポイントUUIDをキャプチャし、復元が必要な場合にrewindFiles()(TypeScript)またはrewind_files()(Python)を呼び出します。
以下の例は完全なフローを示しています:チェックポイントを有効にし、レスポンスストリームからチェックポイントUUIDとセッションIDをキャプチャし、後でセッションを再開してファイルを巻き戻します。各ステップの詳細は以下で説明します。
これらのパターンは、ユースケースに応じてチェックポイントUUIDをキャプチャして使用するさまざまな方法を示しています。
このパターンは、各エージェントターンの前に更新しながら、最新のチェックポイントUUIDのみを保持します。処理中に問題が発生した場合、最後の安全な状態にすぐに巻き戻してループから抜け出すことができます。
Claudeが複数のターンにわたって変更を行う場合、最初まで戻るのではなく、特定のポイントに巻き戻したい場合があります。例えば、Claudeがターン1でファイルをリファクタリングし、ターン2でテストを追加した場合、リファクタリングは保持しつつテストだけを元に戻したい場合があります。
このパターンは、すべてのチェックポイントUUIDをメタデータとともに配列に保存します。セッション完了後、任意の以前のチェックポイントに巻き戻すことができます:
この完全な例では、小さなユーティリティファイルを作成し、エージェントにドキュメントコメントを追加させ、変更を表示してから、巻き戻すかどうかを尋ねます。
始める前に、Claude Agent SDKがインストールされていることを確認してください。
ファイルチェックポイントには以下の制限事項があります:
| 制限事項 | 説明 |
|---|---|
| Write/Edit/NotebookEditツールのみ | Bashコマンドを通じて行われた変更は追跡されない |
| 同一セッション | チェックポイントはそれを作成したセッションに紐づく |
| ファイル内容のみ | ディレクトリの作成、移動、削除は巻き戻しで元に戻されない |
| ローカルファイル | リモートまたはネットワークファイルは追跡されない |
enableFileCheckpointingまたはrewindFiles()が利用できない場合、古いSDKバージョンを使用している可能性があります。
解決策:最新のSDKバージョンに更新してください:
pip install --upgrade claude-agent-sdknpm install @anthropic-ai/claude-agent-sdk@latestmessage.uuidがundefinedまたは欠落している場合、チェックポイントUUIDを受信していません。
原因:replay-user-messagesオプションが設定されていません。
解決策:オプションにextra_args={"replay-user-messages": None}(Python)またはextraArgs: { 'replay-user-messages': null }(TypeScript)を追加してください。
このエラーは、指定されたユーザーメッセージUUIDのチェックポイントデータが存在しない場合に発生します。
一般的な原因:
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING環境変数が設定されていない解決策:環境変数が設定されていることを確認し(環境変数を設定するを参照)、例に示されているパターンを使用してください:最初のユーザーメッセージUUIDをキャプチャし、セッションを完全に完了してから、空のプロンプトで再開し、rewindFiles()を一度呼び出します。
このエラーは、レスポンスの反復処理が完了した後にrewindFiles()またはrewind_files()を呼び出した場合に発生します。ループが完了するとCLIプロセスへの接続が閉じられます。
解決策:空のプロンプトでセッションを再開し、新しいクエリで巻き戻しを呼び出します:
# 空のプロンプトでセッションを再開し、巻き戻す
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("")
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
breakquery()のすべてのオプションとrewindFiles()メソッドを含む完全なAPIリファレンスです。ClaudeAgentOptionsのすべてのオプションとrewind_files()メソッドを含む完全なAPIリファレンスです。import asyncio
import os
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
async def main():
# ステップ1: チェックポイントを有効にする
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits", # プロンプトなしでファイル編集を自動承認
extra_args={"replay-user-messages": None}, # レスポンスストリームでチェックポイントUUIDを受信するために必要
env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)
checkpoint_id = None
session_id = None
# クエリを実行し、チェックポイントUUIDとセッションIDをキャプチャ
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")
# ステップ2: 最初のユーザーメッセージからチェックポイントUUIDをキャプチャ
async for message in client.receive_response():
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
if isinstance(message, ResultMessage) and not session_id:
session_id = message.session_id
# ステップ3: 後で、空のプロンプトでセッションを再開して巻き戻す
if checkpoint_id and session_id:
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # 接続を開くための空のプロンプト
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
break
print(f"Rewound to checkpoint: {checkpoint_id}")
asyncio.run(main())環境変数を設定する
ファイルチェックポイントにはCLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING環境変数が必要です。スクリプトを実行する前にコマンドラインで設定するか、SDKオプションで直接設定できます。
オプション1: コマンドラインで設定
export CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=1オプション2: SDKオプションで設定
SDKを設定する際にenvオプションを通じて環境変数を渡します:
import os
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)チェックポイントを有効にする
チェックポイントを有効にし、チェックポイントUUIDを受信するようにSDKオプションを設定します:
| オプション | Python | TypeScript | 説明 |
|---|---|---|---|
| チェックポイントを有効にする | enable_file_checkpointing=True | enableFileCheckpointing: true | 巻き戻し用にファイル変更を追跡する |
| チェックポイントUUIDを受信する | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | ストリームでユーザーメッセージUUIDを取得するために必要 |
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None}
)
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")チェックポイントUUIDとセッションIDをキャプチャする
replay-user-messagesオプションが設定されている場合(上記参照)、レスポンスストリーム内の各ユーザーメッセージにはチェックポイントとして機能するUUIDがあります。
ほとんどのユースケースでは、最初のユーザーメッセージUUID(message.uuid)をキャプチャします。これに巻き戻すと、すべてのファイルが元の状態に復元されます。複数のチェックポイントを保存して中間状態に巻き戻すには、複数の復元ポイントを参照してください。
セッションID(message.session_id)のキャプチャはオプションです。ストリームが完了した後に巻き戻したい場合にのみ必要です。メッセージを処理中にすぐにrewindFiles()を呼び出す場合(リスクのある操作前のチェックポイントの例のように)、セッションIDのキャプチャはスキップできます。
checkpoint_id = None
session_id = None
async for message in client.receive_response():
# 各ユーザーメッセージでチェックポイントを更新(最新を保持)
if isinstance(message, UserMessage) and message.uuid:
checkpoint_id = message.uuid
# 結果メッセージからセッションIDをキャプチャ
if isinstance(message, ResultMessage):
session_id = message.session_idファイルを巻き戻す
ストリーム完了後に巻き戻すには、空のプロンプトでセッションを再開し、チェックポイントUUIDを指定してrewind_files()(Python)またはrewindFiles()(TypeScript)を呼び出します。ストリーム中に巻き戻すこともできます。そのパターンについてはリスクのある操作前のチェックポイントを参照してください。
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # 接続を開くための空のプロンプト
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
breakセッションIDとチェックポイントIDをキャプチャしている場合、CLIからも巻き戻すことができます:
claude --resume <session-id> --rewind-files <checkpoint-uuid>import asyncio
import os
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage
async def main():
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)
safe_checkpoint = None
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")
async for message in client.receive_response():
# 各エージェントターンの開始前にチェックポイントを更新
# 前のチェックポイントを上書きする。最新のみを保持
if isinstance(message, UserMessage) and message.uuid:
safe_checkpoint = message.uuid
# 独自のロジックに基づいて巻き戻すタイミングを決定
# 例:エラー検出、バリデーション失敗、またはユーザー入力
if your_revert_condition and safe_checkpoint:
await client.rewind_files(safe_checkpoint)
# 巻き戻し後にループを終了、ファイルは復元済み
break
asyncio.run(main())import asyncio
import os
from dataclasses import dataclass
from datetime import datetime
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
# より良い追跡のためにチェックポイントメタデータを保存
@dataclass
class Checkpoint:
id: str
description: str
timestamp: datetime
async def main():
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)
checkpoints = []
session_id = None
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")
async for message in client.receive_response():
if isinstance(message, UserMessage) and message.uuid:
checkpoints.append(Checkpoint(
id=message.uuid,
description=f"After turn {len(checkpoints) + 1}",
timestamp=datetime.now()
))
if isinstance(message, ResultMessage) and not session_id:
session_id = message.session_id
# 後で:セッションを再開して任意のチェックポイントに巻き戻す
if checkpoints and session_id:
target = checkpoints[0] # 任意のチェックポイントを選択
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # 接続を開くための空のプロンプト
async for message in client.receive_response():
await client.rewind_files(target.id)
break
print(f"Rewound to: {target.description}")
asyncio.run(main())テストファイルを作成する
utils.py(Python)またはutils.ts(TypeScript)という新しいファイルを作成し、以下のコードを貼り付けます:
def add(a, b):
return a + b
def subtract(a, b):
return a - b
def multiply(a, b):
return a * b
def divide(a, b):
if b == 0:
raise ValueError("Cannot divide by zero")
return a / bインタラクティブな例を実行する
ユーティリティファイルと同じディレクトリにtry_checkpointing.py(Python)またはtry_checkpointing.ts(TypeScript)という新しいファイルを作成し、以下のコードを貼り付けます。
このスクリプトは、Claudeにユーティリティファイルにドキュメントコメントを追加するよう依頼し、その後、巻き戻して元に戻すオプションを提供します。
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
async def main():
# チェックポイントを有効にしてSDKを設定
# - enable_file_checkpointing: 巻き戻し用にファイル変更を追跡
# - permission_mode: プロンプトなしでファイル編集を自動承認
# - extra_args: ストリームでユーザーメッセージUUIDを受信するために必要
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None}
)
checkpoint_id = None # 巻き戻し用のユーザーメッセージUUIDを保存
session_id = None # 再開用のセッションIDを保存
print("Running agent to add doc comments to utils.py...\n")
# エージェントを実行し、レスポンスストリームからチェックポイントデータをキャプチャ
async with ClaudeSDKClient(options) as client:
await client.query("Add doc comments to utils.py")
async for message in client.receive_response():
# 最初のユーザーメッセージUUIDをキャプチャ - これが復元ポイント
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
# 後で再開できるようにセッションIDをキャプチャ
if isinstance(message, ResultMessage):
session_id = message.session_id
print("Done! Open utils.py to see the added doc comments.\n")
# 変更を巻き戻すかユーザーに尋ねる
if checkpoint_id and session_id:
response = input("Rewind to remove the doc comments? (y/n): ")
if response.lower() == "y":
# 空のプロンプトでセッションを再開し、巻き戻す
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # 空のプロンプトで接続を開く
async for message in client.receive_response():
await client.rewind_files(checkpoint_id) # ファイルを復元
break
print("\n✓ File restored! Open utils.py to verify the doc comments are gone.")
else:
print("\nKept the modified file.")
asyncio.run(main())この例は、チェックポイントの完全なワークフローを示しています:
enable_file_checkpointing=Trueとpermission_mode="acceptEdits"でSDKを設定し、ファイル編集を自動承認するrewind_files()を呼び出して元のファイルを復元する例を実行する
環境変数を設定し、ユーティリティファイルと同じディレクトリからスクリプトを実行します。
スクリプトを実行する前に、ユーティリティファイル(utils.pyまたはutils.ts)をIDEまたはエディタで開いてください。エージェントがドキュメントコメントを追加するとファイルがリアルタイムで更新され、巻き戻しを選択すると元に戻るのが確認できます。
エージェントがドキュメントコメントを追加し、巻き戻すかどうかを尋ねるプロンプトが表示されます。はいを選択すると、ファイルは元の状態に復元されます。