Skip to main content
File checkpointing melacak modifikasi file yang dilakukan melalui alat Write, Edit, dan NotebookEdit selama sesi agen, memungkinkan Anda untuk mengembalikan file ke status sebelumnya. Untuk melihat rewind memulihkan file, lompat ke contoh interaktif.
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, dan juga tidak ada edit yang diterapkan subagen, kecuali skill dengan context: fork yang berjalan di foreground.

Cara kerja checkpointing

Ketika Anda mengaktifkan file checkpointing, SDK membuat cadangan file sebelum memodifikasinya melalui alat Write, Edit, atau NotebookEdit. Pesan pengguna dalam aliran respons menyertakan UUID checkpoint yang dapat Anda gunakan sebagai titik pemulihan.
Pemulihan file mengembalikan file di disk ke status sebelumnya. Ini tidak mengembalikan percakapan itu sendiri. Riwayat percakapan dan konteks tetap utuh setelah memanggil rewindFiles() (TypeScript) atau rewind_files() (Python).
Ketika Anda mengembalikan ke checkpoint, Claude Code menghapus file yang dibuat dan memulihkan file yang dimodifikasi ke konten mereka pada titik itu. Claude Code melewati jalur terlacak yang merupakan symlink, hard link, atau file non-reguler lainnya. Ini juga melewati file terlacak yang direktori induknya tidak lagi menyelesaikan ke lokasi waktu checkpoint-nya, atau yang cadangannya tidak dapat dibaca dengan aman. RewindFilesResult menghitung setiap jalur yang dilewati dalam bidang skippedLinks-nya. Melewati memerlukan Claude Code v2.1.216 atau lebih baru; sebelum v2.1.216, rewind menulis dan menghapus melalui tautan di jalur terlacak.

Implementasikan checkpointing

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-contoh di bagian ini menggunakan prompt “Refactor the authentication module”. Jalankan mereka dalam proyek yang berisi modul autentikasi, atau ubah prompt untuk menamai file yang ada di proyek Anda, sehingga Anda dapat menonton file berubah dan melihat rewind memulihkannya. Contoh ini mengaktifkan checkpointing, menangkap UUID checkpoint dan ID sesi dari aliran respons, kemudian melanjutkan sesi nanti untuk mengembalikan file. Komentar bernomor contoh cocok dengan langkah-langkah yang mengikuti.
1

Aktifkan checkpointing

Konfigurasi opsi SDK Anda untuk mengaktifkan checkpointing dan menerima UUID checkpoint:Contoh utama di bawah Implementasikan checkpointing juga menetapkan mode izin ke acceptEdits, yang menyetujui pengeditan file agen tanpa prompt. Untuk informasi lebih lanjut, lihat Mode izin.
2

Tangkap UUID checkpoint dan ID sesi

Dengan opsi replay-user-messages yang diatur, setiap pesan pengguna dalam aliran respons memiliki UUID yang berfungsi sebagai checkpoint.Untuk sebagian besar kasus penggunaan, tangkap UUID pesan pengguna pertama (message.uuid); mengembalikan ke sana memulihkan semua file ke status asli mereka. Untuk menyimpan beberapa checkpoint dan mengembalikan ke status perantara, lihat Beberapa titik pemulihan.Menangkap ID sesi (message.session_id) bersifat opsional; Anda hanya membutuhkannya jika Anda ingin mengembalikan 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.
3

Kembalikan file

Untuk mengembalikan setelah aliran selesai, lanjutkan sesi dengan prompt kosong dan panggil rewind_files() (Python) atau rewindFiles() (TypeScript) dengan UUID checkpoint Anda. Aktifkan checkpointing pada opsi sesi yang dilanjutkan juga, dan panggil rewind dari dalam loop respons. Anda juga dapat mengembalikan selama aliran. Lihat Checkpoint sebelum operasi berisiko untuk pola itu.Jika Anda menangkap ID sesi dan ID checkpoint, Anda juga dapat mengembalikan dari CLI. Perintah ini memerlukan executable claude, yang berasal dari menginstal Claude Code. SDK mengaktifkan checkpointing untuk Anda, tetapi ketika Anda menjalankan claude -p secara langsung, Anda harus mengatur variabel lingkungan CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING:
Flag --rewind-files tidak muncul dalam output claude --help, tetapi CLI menerimanya seperti yang ditunjukkan. Ketika rewind berhasil, perintah mencetak Files rewound to state at message <checkpoint-uuid> dan keluar tanpa mengirim prompt.

Pola umum

Pola ini menunjukkan cara berbeda untuk menangkap dan menggunakan UUID checkpoint tergantung pada kasus penggunaan Anda.

Checkpoint sebelum operasi berisiko

Pola ini menyimpan hanya UUID checkpoint terbaru, memperbaruinya sebelum setiap putaran agen. Jika ada yang salah selama pemrosesan, Anda dapat segera mengembalikan ke status terakhir yang aman dan keluar dari loop. Sebelum menjalankan contoh ini, ganti your_revert_condition (Python) atau yourRevertCondition (TypeScript) dengan pemeriksaan Anda sendiri, seperti deteksi kesalahan atau kegagalan validasi; placeholder tidak didefinisikan dalam contoh.

Beberapa titik pemulihan

Jika Claude membuat perubahan di beberapa putaran, Anda mungkin ingin mengembalikan 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 mengembalikan ke checkpoint sebelumnya:

Coba sekarang

Contoh lengkap ini membuat file utilitas kecil, meminta agen menambahkan komentar dokumentasi, menunjukkan perubahan kepada Anda, kemudian menanyakan apakah Anda ingin mengembalikan. Sebelum Anda mulai, pastikan Anda telah menginstal Claude Agent SDK.
1

Buat file uji

Buat file baru bernama utils.py (Python) atau utils.ts (TypeScript) dan tempel kode berikut:
2

Jalankan 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 mengembalikan dan memulihkan yang asli.
3

Jalankan contoh

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 mengembalikan.
Anda akan melihat agen menambahkan komentar doc, kemudian prompt yang menanyakan apakah Anda ingin mengembalikan. Jika Anda memilih ya, file dipulihkan ke status aslinya.

Keterbatasan

File checkpointing memiliki keterbatasan berikut:

Troubleshooting

Opsi checkpointing tidak dikenali

Jika enableFileCheckpointing atau rewindFiles() tidak tersedia, Anda mungkin menggunakan versi SDK yang lebih lama. Solusi: Perbarui ke versi SDK terbaru:
  • Python: pip install --upgrade claude-agent-sdk
  • TypeScript: npm install @anthropic-ai/claude-agent-sdk@latest

Pesan pengguna tidak memiliki UUID

Jika 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 “No file checkpoint found for this message”

Kesalahan ini terjadi ketika data checkpoint tidak ada untuk UUID pesan pengguna yang ditentukan. Penyebab umum:
  • File checkpointing tidak diaktifkan pada sesi asli (enable_file_checkpointing atau enableFileCheckpointing tidak diatur ke true)
  • Sesi tidak diselesaikan dengan benar sebelum mencoba melanjutkan dan mengembalikan
Solusi: Pastikan enable_file_checkpointing=True (Python) atau enableFileCheckpointing: true (TypeScript) diatur pada sesi asli, 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 “File rewinding is not enabled”

Kesalahan ini terjadi ketika Anda mencoba rewind non-interaktif tanpa checkpointing diaktifkan: menjalankan claude -p biasa dengan --rewind-files, atau menjalankan sesi SDK, termasuk sesi yang dilanjutkan, yang opsinya tidak mengaktifkan checkpointing. SDK menetapkan variabel lingkungan CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING secara internal hanya ketika enable_file_checkpointing (Python) atau enableFileCheckpointing (TypeScript) diaktifkan pada sesi yang melakukan rewind; CLI biasa tidak pernah menetapkannya. Solusi: Untuk CLI biasa, atur variabel lingkungan saat menjalankan perintah:
Untuk SDK, atur enable_file_checkpointing=True (Python) atau enableFileCheckpointing: true (TypeScript) pada sesi yang dilanjutkan, seperti yang dilakukan contoh di halaman ini.

Kesalahan “ProcessTransport is not ready for writing”

Kesalahan ini terjadi ketika Anda memanggil rewindFiles() atau rewind_files() setelah Anda selesai mengulangi respons. Koneksi ke proses CLI ditutup ketika loop selesai. Solusi: Lanjutkan sesi dengan prompt kosong, kemudian panggil rewind pada kueri baru. Contoh utama di bawah Implement checkpointing menunjukkan panggilan resume-and-rewind di kedua bahasa, pada komentar yang ditandai Langkah 3.

Langkah berikutnya

  • Sessions: pelajari cara melanjutkan sesi, yang diperlukan untuk pemulihan setelah aliran selesai. Mencakup ID sesi, melanjutkan percakapan, dan forking sesi.
  • Permissions: konfigurasi alat mana yang dapat digunakan Claude dan bagaimana modifikasi file disetujui. Berguna jika Anda menginginkan kontrol lebih besar atas kapan pengeditan terjadi.
  • Referensi SDK TypeScript: referensi API lengkap termasuk semua opsi untuk query() dan metode rewindFiles().
  • Referensi SDK Python: referensi API lengkap termasuk semua opsi untuk ClaudeAgentOptions dan metode rewind_files().