File checkpointing melacak modifikasi file yang dilakukan melalui alat Write, Edit, dan NotebookEdit selama sesi agen, memungkinkan Anda untuk membatalkan file ke status sebelumnya. Ingin mencobanya? Lompat ke contoh interaktif.
Dengan checkpointing, Anda dapat:
Hanya perubahan yang dilakukan melalui alat Write, Edit, dan NotebookEdit yang dilacak. Perubahan yang dilakukan melalui perintah Bash (seperti echo > file.txt atau sed -i) tidak ditangkap oleh sistem checkpoint.
Ketika Anda mengaktifkan file checkpointing, SDK membuat cadangan file sebelum memodifikasinya melalui alat Write, Edit, atau NotebookEdit. Pesan pengguna dalam aliran respons mencakup UUID checkpoint yang dapat Anda gunakan sebagai titik pemulihan.
Checkpoint bekerja dengan alat bawaan ini yang digunakan agen untuk memodifikasi file:
| Alat | Deskripsi |
|---|---|
| Write | Membuat file baru atau menimpa file yang ada dengan konten baru |
| Edit | Membuat pengeditan yang ditargetkan ke bagian tertentu dari file yang ada |
| NotebookEdit | Memodifikasi sel dalam notebook Jupyter (file .ipynb) |
Pembatalan file memulihkan file di disk ke status sebelumnya. Ini tidak membatalkan percakapan itu sendiri. Riwayat percakapan dan konteks tetap utuh setelah memanggil rewindFiles() (TypeScript) atau rewind_files() (Python).
Sistem checkpoint melacak:
Ketika Anda membatalkan ke checkpoint, file yang dibuat dihapus dan file yang dimodifikasi dipulihkan ke konten mereka pada titik itu.
Untuk menggunakan file checkpointing, aktifkan dalam opsi Anda, tangkap UUID checkpoint dari aliran respons, kemudian panggil rewindFiles() (TypeScript) atau rewind_files() (Python) ketika Anda perlu memulihkan.
Contoh berikut menunjukkan alur lengkap: aktifkan checkpointing, tangkap UUID checkpoint dan ID sesi dari aliran respons, kemudian lanjutkan sesi nanti untuk membatalkan file. Setiap langkah dijelaskan secara detail di bawah.
Pola ini menunjukkan cara berbeda untuk menangkap dan menggunakan UUID checkpoint tergantung pada kasus penggunaan Anda.
Pola ini menyimpan hanya UUID checkpoint paling baru, memperbarui sebelum setiap putaran agen. Jika ada yang salah selama pemrosesan, Anda dapat segera membatalkan ke status terakhir yang aman dan keluar dari loop.
Jika Claude membuat perubahan di beberapa putaran, Anda mungkin ingin membatalkan ke titik tertentu daripada semuanya. Misalnya, jika Claude merefaktor file di putaran satu dan menambahkan tes di putaran dua, Anda mungkin ingin menyimpan refaktor tetapi membatalkan tes.
Pola ini menyimpan semua UUID checkpoint dalam array dengan metadata. Setelah sesi selesai, Anda dapat membatalkan ke checkpoint sebelumnya:
Contoh lengkap ini membuat file utilitas kecil, membuat agen menambahkan komentar dokumentasi, menunjukkan perubahan kepada Anda, kemudian menanyakan apakah Anda ingin membatalkan.
Sebelum Anda mulai, pastikan Anda telah menginstal Claude Agent SDK.
File checkpointing memiliki keterbatasan berikut:
| Keterbatasan | Deskripsi |
|---|---|
| Alat Write/Edit/NotebookEdit saja | Perubahan yang dilakukan melalui perintah Bash tidak dilacak |
| Sesi yang sama | Checkpoint terikat pada sesi yang membuatnya |
| Konten file saja | Membuat, memindahkan, atau menghapus direktori tidak dibatalkan oleh pembatalan |
| File lokal | File jarak jauh atau jaringan tidak dilacak |
Jika enableFileCheckpointing atau rewindFiles() tidak tersedia, Anda mungkin menggunakan versi SDK yang lebih lama.
Solusi: Perbarui ke versi SDK terbaru:
pip install --upgrade claude-agent-sdknpm install @anthropic-ai/claude-agent-sdk@latestJika message.uuid adalah undefined atau hilang, Anda tidak menerima UUID checkpoint.
Penyebab: Opsi replay-user-messages tidak diatur.
Solusi: Tambahkan extra_args={"replay-user-messages": None} (Python) atau extraArgs: { 'replay-user-messages': null } (TypeScript) ke opsi Anda.
Kesalahan ini terjadi ketika data checkpoint tidak ada untuk UUID pesan pengguna yang ditentukan.
Penyebab umum:
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING tidak diaturSolusi: Pastikan Anda telah mengatur variabel lingkungan (lihat Atur variabel lingkungan), kemudian gunakan pola yang ditunjukkan dalam contoh: tangkap UUID pesan pengguna pertama, selesaikan sesi sepenuhnya, kemudian lanjutkan dengan prompt kosong dan panggil rewindFiles() sekali.
Kesalahan ini terjadi ketika Anda memanggil rewindFiles() atau rewind_files() setelah Anda selesai melakukan iterasi melalui respons. Koneksi ke proses CLI ditutup ketika loop selesai.
Solusi: Lanjutkan sesi dengan prompt kosong, kemudian batalkan pada kueri baru:
# Resume session with empty prompt, then rewind
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() dan metode rewindFiles().ClaudeAgentOptions dan metode rewind_files().import asyncio
import os
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
async def main():
# Step 1: Enable checkpointing
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits", # Auto-accept file edits without prompting
extra_args={"replay-user-messages": None}, # Required to receive checkpoint UUIDs in the response stream
env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)
checkpoint_id = None
session_id = None
# Run the query and capture checkpoint UUID and session ID
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")
# Step 2: Capture checkpoint UUID from the first user message
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
# Step 3: Later, rewind by resuming the session with an empty prompt
if checkpoint_id and session_id:
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
break
print(f"Rewound to checkpoint: {checkpoint_id}")
asyncio.run(main())Atur variabel lingkungan
File checkpointing memerlukan variabel lingkungan CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING. Anda dapat mengaturnya melalui baris perintah sebelum menjalankan skrip Anda, atau langsung dalam opsi SDK.
Opsi 1: Atur melalui baris perintah
export CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=1Opsi 2: Atur dalam opsi SDK
Lewatkan variabel lingkungan melalui opsi env saat mengonfigurasi SDK:
import os
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
)Aktifkan checkpointing
Konfigurasikan opsi SDK Anda untuk mengaktifkan checkpointing dan menerima UUID checkpoint:
| Opsi | Python | TypeScript | Deskripsi |
|---|---|---|---|
| Aktifkan checkpointing | enable_file_checkpointing=True | enableFileCheckpointing: true | Melacak perubahan file untuk pembatalan |
| Terima UUID checkpoint | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Diperlukan untuk mendapatkan UUID pesan pengguna dalam aliran |
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")Tangkap UUID checkpoint dan ID sesi
Dengan opsi replay-user-messages yang diatur (ditunjukkan di atas), setiap pesan pengguna dalam aliran respons memiliki UUID yang berfungsi sebagai checkpoint.
Untuk sebagian besar kasus penggunaan, tangkap UUID pesan pengguna pertama (message.uuid); pembatalan ke sana memulihkan semua file ke status asli mereka. Untuk menyimpan beberapa checkpoint dan membatalkan ke status perantara, lihat Beberapa titik pemulihan.
Menangkap ID sesi (message.session_id) bersifat opsional; Anda hanya membutuhkannya jika Anda ingin membatalkan nanti, setelah aliran selesai. Jika Anda memanggil rewindFiles() segera saat masih memproses pesan (seperti yang dilakukan contoh di Checkpoint sebelum operasi berisiko), Anda dapat melewatkan penangkapan ID sesi.
checkpoint_id = None
session_id = None
async for message in client.receive_response():
# Update checkpoint on each user message (keeps the latest)
if isinstance(message, UserMessage) and message.uuid:
checkpoint_id = message.uuid
# Capture session ID from the result message
if isinstance(message, ResultMessage):
session_id = message.session_idBatalkan file
Untuk membatalkan setelah aliran selesai, lanjutkan sesi dengan prompt kosong dan panggil rewind_files() (Python) atau rewindFiles() (TypeScript) dengan UUID checkpoint Anda. Anda juga dapat membatalkan selama aliran; lihat Checkpoint sebelum operasi berisiko untuk pola itu.
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
breakJika Anda menangkap ID sesi dan ID checkpoint, Anda juga dapat membatalkan dari 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():
# Update checkpoint before each agent turn starts
# This overwrites the previous checkpoint. Only keep the latest
if isinstance(message, UserMessage) and message.uuid:
safe_checkpoint = message.uuid
# Decide when to revert based on your own logic
# For example: error detection, validation failure, or user input
if your_revert_condition and safe_checkpoint:
await client.rewind_files(safe_checkpoint)
# Exit the loop after rewinding, files are restored
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
# Store checkpoint metadata for better tracking
@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
# Later: rewind to any checkpoint by resuming the session
if checkpoints and session_id:
target = checkpoints[0] # Pick any checkpoint
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(target.id)
break
print(f"Rewound to: {target.description}")
asyncio.run(main())Buat file uji
Buat file baru bernama utils.py (Python) atau utils.ts (TypeScript) dan tempel kode berikut:
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 / bJalankan contoh interaktif
Buat file baru bernama try_checkpointing.py (Python) atau try_checkpointing.ts (TypeScript) di direktori yang sama dengan file utilitas Anda, dan tempel kode berikut.
Skrip ini meminta Claude untuk menambahkan komentar doc ke file utilitas Anda, kemudian memberi Anda opsi untuk membatalkan dan memulihkan yang asli.
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
async def main():
# Configure the SDK with checkpointing enabled
# - enable_file_checkpointing: Track file changes for rewinding
# - permission_mode: Auto-accept file edits without prompting
# - extra_args: Required to receive user message UUIDs in the stream
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None}
)
checkpoint_id = None # Store the user message UUID for rewinding
session_id = None # Store the session ID for resuming
print("Running agent to add doc comments to utils.py...\n")
# Run the agent and capture checkpoint data from the response stream
async with ClaudeSDKClient(options) as client:
await client.query("Add doc comments to utils.py")
async for message in client.receive_response():
# Capture the first user message UUID - this is our restore point
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
# Capture the session ID so we can resume later
if isinstance(message, ResultMessage):
session_id = message.session_id
print("Done! Open utils.py to see the added doc comments.\n")
# Ask the user if they want to rewind the changes
if checkpoint_id and session_id:
response = input("Rewind to remove the doc comments? (y/n): ")
if response.lower() == "y":
# Resume the session with an empty prompt, then rewind
async with ClaudeSDKClient(ClaudeAgentOptions(
enable_file_checkpointing=True,
resume=session_id
)) as client:
await client.query("") # Empty prompt opens the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id) # Restore files
break
print("\n✓ File restored! Open utils.py to verify the doc comments are gone.")
else:
print("\nKept the modified file.")
asyncio.run(main())Contoh ini mendemonstrasikan alur kerja checkpointing lengkap:
enable_file_checkpointing=True dan permission_mode="acceptEdits" untuk menyetujui pengeditan file secara otomatisrewind_files() untuk memulihkan file asliJalankan contoh
Atur variabel lingkungan dan jalankan skrip dari direktori yang sama dengan file utilitas Anda.
Buka file utilitas Anda (utils.py atau utils.ts) di IDE atau editor Anda sebelum menjalankan skrip. Anda akan melihat file diperbarui secara real-time saat agen menambahkan komentar doc, kemudian kembali ke asli ketika Anda memilih untuk membatalkan.
export CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=1
python try_checkpointing.pyAnda akan melihat agen menambahkan komentar doc, kemudian prompt menanyakan apakah Anda ingin membatalkan. Jika Anda memilih ya, file dipulihkan ke status aslinya.