Bagaimana Claude Code menggunakan prompt caching

Claude Code mengelola prompt caching secara otomatis. Lihat mengapa perubahan model memicu giliran tanpa cache yang lambat, berapa biaya /compact, mengapa pengeditan CLAUDE.md tidak berlaku di tengah sesi, dan cara memeriksa tingkat cache hit Anda.

Prompt caching membuat Claude Code lebih cepat dan lebih hemat biaya. Tanpa caching, API akan memproses ulang riwayat lengkap Anda pada setiap giliran. Dengan caching, API menggunakan kembali apa yang sudah diproses, menagih pembacaan ulang pada tingkat token cache, dan hanya memproses sepenuhnya apa yang berubah.

Claude Code menangani prompt caching untuk Anda, kecuali Anda menonaktifkannya. Masih berguna untuk mengetahui cara kerja prompt caching, karena beberapa tindakan membatalkan cache dan membuat respons berikutnya lebih lambat dan lebih mahal saat membangun kembali. Halaman ini mencakup tindakan mana yang melakukan itu, mengapa beberapa pengaturan menunggu restart untuk diterapkan, dan cara memeriksa kinerja cache ketika penggunaan terlihat tinggi.

Bagaimana cache diorganisir

Setiap kali Anda mengirim pesan di Claude Code, sistem membuat permintaan API baru. Model tidak mengingat apa pun di antara permintaan, jadi Claude Code mengirim ulang konteks lengkap: prompt sistem, konteks proyek Anda, setiap pesan dan hasil alat sebelumnya, dan pesan baru Anda. Konten baru ditambahkan di akhir, yang berarti sebagian besar dari setiap permintaan identik dengan yang sebelumnya. Prompt caching adalah cara API menghindari pemrosesan ulang bagian yang tidak berubah.

API melakukan cache dengan mencocokkan awal setiap permintaan, yang disebut prefix, terhadap konten yang baru saja diproses. Pada giliran normal, prefix adalah seluruh permintaan sebelumnya dan hanya pertukaran terbaru yang baru. Kecocokan bersifat tepat, jadi perubahan di mana pun dalam prefix menghitung ulang semuanya setelahnya. Tidak ada caching per-file atau per-segment. Lihat bagaimana prompt caching bekerja dalam referensi API untuk mekanisme yang mendasarinya.

Untuk mendapatkan hasil maksimal dari pencocokan prefix, Claude Code mengurutkan setiap permintaan sehingga konten yang jarang berubah di antara giliran muncul terlebih dahulu:

Perubahan pada layer percakapan meninggalkan prompt sistem dan konteks proyek di-cache. Perubahan pada prompt sistem membatalkan semuanya, karena semua konten selanjutnya sekarang berada di belakang prefix yang berbeda. Kolom ketiga memberikan pemicu umum daripada daftar lengkap, dan bagian di bawah mencakup set lengkap.

Aturan pencocokan prefix menjelaskan sebagian besar perilaku di halaman ini. Plan mode dan skill loading, misalnya, menambahkan instruksi mereka sebagai pesan percakapan, jadi prefix yang di-cache tetap utuh.

Dua pengaturan tidak muncul dalam tabel layer tetapi masih mempengaruhi apa yang tetap di-cache:

• Model: setiap model memiliki cache-nya sendiri. Mengganti model menghitung ulang seluruh permintaan bahkan ketika kontennya identik. Lihat Switching models di bawah.
• Effort level: pada sebagian besar model, setiap effort level memiliki cache-nya sendiri, jadi mengubah effort di tengah sesi menghitung ulang seluruh permintaan. Pada Fable 5.1 dengan API key atau langganan Claude, cache tetap utuh secara default. Lihat Changing effort level di bawah.

Tempat cache berada

Caching terjadi di sisi server, dalam infrastruktur apa pun yang melayani model Anda. Tempat itu tergantung pada cara Anda melakukan autentikasi:

• API key, langganan Claude, atau Claude Platform on AWS: cache berada di infrastruktur Anthropic, diakses melalui Claude API
• Amazon Bedrock atau Agent Platform Google Cloud: cache berada di infrastruktur serving penyedia cloud Anda
• Microsoft Foundry: tergantung pada hosting option deployment. Deployment yang di-host di Azure dilayani di infrastruktur Azure; deployment yang di-host di Anthropic dilayani di infrastruktur Anthropic
• Custom ANTHROPIC_BASE_URL atau LLM gateway: cache berada di mana pun permintaan Anda diteruskan, dan apakah caching bekerja tergantung pada gateway

Claude Code juga menambahkan konteks sistem di tengah percakapan, seperti pemberitahuan perubahan file, dan menandai blok itu untuk caching di setiap penyedia dan koneksi kecuali Anda menetapkan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, dalam hal ini blok itu dikirim tanpa cache.

Di endpoint penyedia sendiri, Amazon Bedrock dan Mantle endpoint-nya, Agent Platform Google Cloud, dan Microsoft Foundry melakukan cache pada blok dengan cara yang sama seperti Claude API.

Ketika permintaan Anda melewati LLM gateway, custom ANTHROPIC_BASE_URL, atau cloud provider base-URL override seperti ANTHROPIC_BEDROCK_BASE_URL, apa yang tetap di-cache tergantung pada cara gateway menangani cache_control markers yang dikirim Claude Code:

• Meneruskannya tanpa perubahan: blok dan percakapan Anda melakukan cache dengan cara yang sama seperti di endpoint penyedia sendiri.
• Menolak permintaan yang ditandai dengan error 400 yang menyebutkan cache_control: Claude Code mengirim ulang permintaan dengan marker dipindahkan dari blok dan ke pesan percakapan terakhir Anda, dan menyimpannya di sana untuk sisa percakapan. Blok ditagih sebagai uncached input; percakapan Anda tetap di-cache.
• Menghapus marker sambil mengembalikan kesuksesan: seluruh riwayat percakapan Anda ditagih sebagai uncached input di setiap giliran. Gateway yang mengonversi konten sistem bentuk blok ke string biasa menghapus marker dengan cara yang sama.

Untuk apa yang disimpan dan diproses setiap penyedia, lihat data usage. Di mana pun cache berada, entri kedaluwarsa setelah periode tidak aktif, dan Cache lifetime di bawah mencakup TTL dan cara memperpanjangnya.

Tindakan yang membatalkan cache

Tindakan-tindakan ini menyebabkan permintaan berikutnya kehilangan sebagian atau seluruh cache. Anda akan melihat satu putaran yang lebih lambat dan lebih mahal, setelah itu prefiks baru akan di-cache. Sebagian besar dari tindakan ini dapat dihindari di tengah tugas setelah Anda mengetahui bahwa tindakan tersebut memiliki biaya. Pergantian model dapat terasa gratis sampai Anda memperhatikan putaran yang lebih lambat setelahnya.

• Switching models
• Changing effort level
• Turning on fast mode
• Connecting or disconnecting an MCP server
• Enabling or disabling a plugin
• Denying an entire tool
• Compacting the conversation
• Accumulating many images
• Upgrading Claude Code

Switching models

Setiap model memiliki cache-nya sendiri. Beralih dengan /model berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hits, meskipun kontennya identik.

Ketika Anda menjalankan /model di terminal, Claude Code meminta Anda untuk mengonfirmasi pergantian hanya saat cache masih hangat dan model baru bukan yang menghasilkan respons terakhir. Cache tetap hangat selama satu cache TTL setelah Claude Code terakhir mengirim permintaan dalam percakapan ini atau Claude terakhir merespons. Setelah waktu itu berlalu, cache telah kedaluwarsa, jadi Claude Code beralih tanpa bertanya.

Sebelum v2.1.238, Claude Code tidak memeriksa cache TTL dan bertanya bahkan setelah cache telah kedaluwarsa.

Anda juga dapat memerlukan konfirmasi ini atau melewatkannya dengan PreModelSwitch hook.

opusplan model setting diselesaikan ke Opus selama plan mode dan Sonnet selama eksekusi, jadi setiap toggle plan-mode adalah pergantian model dan memulai cache segar.

Automatic model fallback pada model Fable dan Opus 5 juga merupakan pergantian model. Ketika pengklasifikasi keamanan menandai permintaan dalam kategori yang memiliki model fallback, Claude Code menjalankan kembali permintaan pada model tersebut dan sesi berlanjut di sana.

Ketika frontmatter skill atau command menamai model selain model saat ini sesi, putaran itu juga merupakan pergantian model: permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hits. Model sesi dilanjutkan pada prompt Anda berikutnya. Skill context: fork menetapkan model subagent yang di-fork sebagai gantinya.

Changing effort level

Pada sebagian besar model, mengubah effort level di tengah sesi berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hits. Saat cache masih hangat, Claude Code meminta Anda untuk mengonfirmasi perubahan terlebih dahulu.

Pada Fable 5.1 dengan API key atau langganan Claude, mengubah effort menjaga cache, dan Claude Code menerapkan level baru tanpa bertanya. Ini tidak berlaku pada Amazon Bedrock, Google Cloud's Agent Platform, atau Claude apps gateway, atau ketika Anda menetapkan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS atau organisasi Anda memiliki konfigurasi HIPAA.

Sebelum v2.1.260, mengubah effort pada Fable 5.1 dengan API key atau langganan Claude juga membatalkan cache.

Turning on fast mode

Mengaktifkan fast mode menambahkan header permintaan yang merupakan bagian dari cache key, jadi permintaan pertama yang Claude Code kirim dengan fast mode aktif membaca seluruh riwayat percakapan tanpa cache hits. Claude Code menetapkan header itu sekali ketika putaran dimulai dan menyimpannya untuk seluruh putaran, jadi ketika Anda mengaktifkan fast mode saat Claude sedang bekerja, cache miss dari header terjadi pada permintaan pertama putaran Anda berikutnya. Token input yang tidak di-cache tersebut ditagih dengan fast mode rates, itulah mengapa mengaktifkannya di awal sesi biaya lebih rendah daripada mengaktifkannya jauh ke dalam sesi yang panjang. Jika model saat ini Anda tidak mendukung fast mode, mengaktifkan fast mode juga beralih model Anda, dan pergantian itu memulai cache segar pada permintaan berikutnya dalam putaran yang sedang berjalan.

Biaya berlaku sekali per percakapan. Setelah putaran fast mode pertama, Claude Code terus mengirim header dan hanya memvariasikan pengaturan kecepatan permintaan, yang bukan bagian dari cache key. Mematikan fast mode, fallback otomatis ke kecepatan standar setelah rate limit, dan mengaktifkannya kembali nanti semua menjaga cache. Jika Anda kehabisan kredit penggunaan di tengah sesi, Claude Code mencoba kembali setiap permintaan fast mode yang ditolak dengan kecepatan standar dengan cara yang sama, jadi fallback ini juga menjaga cache. /clear dan /compact mengatur ulang ini, karena mereka membangun kembali cache pada titik-titik tersebut bagaimanapun.

Connecting or disconnecting an MCP server

Definisi tool berada di lapisan system prompt, jadi cache membatalkan ketika set definisi tool dalam permintaan berubah antar putaran. Mengalihkan advisor tool adalah pengecualian: definisinya berada setelah breakpoint cache, jadi mengaktifkan atau menonaktifkan /advisor menjaga prefiks yang di-cache tetap utuh. Apakah perubahan MCP server melakukan ini tergantung pada apakah toolnya ditangguhkan oleh tool search atau dimuat ke dalam prefiks:

• Deferred tools, default pada model yang didukung: server yang terhubung, terputus, atau mengubah daftar toolnya hanya menambahkan konten baru dan tidak mengganggu apa pun yang sudah di-cache.
• Tools loaded into the prefix: perubahan apa pun pada mereka membatalkan cache. Ini terjadi ketika tool search tidak tersedia atau dinonaktifkan, seperti pada model Google Cloud's Agent Platform lebih awal dari generasi Claude 4.5, dengan gateway ANTHROPIC_BASE_URL kustom, atau pada deployment Microsoft Foundry yang dihosting di Azure setelah Claude Code mendeteksi bahwa deployment menolak tool search. Ini juga terjadi untuk server atau tool yang ditandai alwaysLoad, dan untuk definisi yang disimpan di depan oleh threshold-based loading.

Ketika tools dimuat ke dalam prefiks, penyebab paling umum dari pembatalan adalah server yang terhubung atau terputus di tengah sesi, yang dapat terjadi tanpa tindakan apa pun dari pihak Anda: proses server stdio keluar, sesi HTTP kedaluwarsa, atau server reconnects automatically after a transient failure. Server yang terhubung juga dapat mendorong dynamic tool update yang mengubah daftar toolnya.

Mengedit konfigurasi MCP Anda tidak dengan sendirinya mengubah cache. Konfigurasi baru hanya berlaku setelah restart, yaitu ketika server terhubung atau terputus.

Enabling or disabling a plugin

Ketika Anda mengaktifkan atau menonaktifkan plugin, apa yang perubahan biaya tergantung pada jenis komponen apa yang disediakan plugin. Kasus-kasus di bawah mencakup setiap jenis komponen, kapan Claude Code menerapkan perubahan, dan apa yang terjadi ketika Anda menonaktifkan plugin lagi dalam sesi yang sama.

Plugin components that keep the cache

Claude Code tidak pernah membatalkan cache untuk skills, commands, agents, hooks, monitors, atau themes plugin. Ini menambahkan konten mereka setelah percakapan yang ada, jadi permintaan berikutnya membayar untuk konten itu dan masih membaca semuanya sebelumnya dari cache.

Plugins that provide MCP servers

Ketika Anda mengaktifkan atau menonaktifkan plugin yang menyediakan MCP servers, Claude Code mengikuti aturan yang sama seperti ketika Anda connect or disconnect an MCP server:

• Jika Claude Code menunda tools server, itu menjaga cache.
• Jika Claude Code memuatnya ke dalam prefiks, permintaan berikutnya membaca ulang seluruh percakapan.

Code intelligence plugins

Ketika Anda mengaktifkan code intelligence plugin, Claude mendapatkan LSP tool.

When plugin changes apply

Perubahan yang Anda buat di menu /plugin melalui /reload-plugins, yang Claude Code jalankan untuk Anda ketika Anda menutup menu. Anda membayar biaya, apakah pengumuman yang ditambahkan atau pembacaan ulang penuh, pada putaran pertama setelah perubahan diterapkan. Claude Code juga dapat menerapkan perubahan dengan sendirinya:

• Untuk plugin dengan sumber command, Claude Code can reload the plugin itself.
• Ketika Anda install a plugin from the /plugin interface, Claude Code dapat mengaktifkannya selama instalasi. Ringkasan instalasi memberi tahu Anda apakah itu dilakukan.
• Ketika Anda move the session with /cd pada v2.1.246 atau lebih baru, Claude Code menerapkan plugin yang diaktifkan pengaturan direktori baru sebagai bagian dari perpindahan, tanpa peringatan pembacaan ulang penuh yang menahan /reload-plugins.
• Dalam sesi interaktif, ketika Anda menambah atau menghapus plugin dalam folder of plugins yang Anda lewatkan dengan --plugin-dir, perubahan diterapkan segera. Jika menerapkannya akan memicu pembacaan ulang penuh, Claude Code menahan perubahan sebagai gantinya dan menampilkan pemberitahuan untuk menjalankan /reload-plugins. Memerlukan Claude Code v2.1.265 atau lebih baru.

Ketika /reload-plugins berjalan dan reload akan memicu pembacaan ulang penuh, Claude Code menampilkan peringatan dan tidak menerapkan reload. Jalankan /reload-plugins --force untuk menerapkannya bagaimanapun.

/reload-plugins juga berjalan dalam sesi tanpa terminal interaktif, seperti aplikasi desktop, Agent SDK, dan non-interactive mode dengan -p, ketika Anda mengetiknya langsung ke sesi. Memerlukan Claude Code v2.1.260 atau lebih baru.

Dalam sesi-sesi itu reload menerapkan semuanya kecuali perubahan MCP server plugin, yang take effect in your next session dan jadi tidak pernah biaya pembacaan ulang penuh di tengah sesi.

Plugins you enable and then disable in one session

Ketika Anda menonaktifkan plugin yang Anda aktifkan sebelumnya dalam sesi, Claude Code mengembalikan bentuk permintaan sebelumnya. Jika prefiks itu masih dalam cache lifetime-nya, permintaan berikutnya membaca entri cache yang lebih lama sebagai gantinya dari membangun kembali.

Denying an entire tool

Jika Anda menambahkan nama tool telanjang seperti Bash atau WebFetch sebagai deny rule, Claude tidak dapat memanggil tool itu dari permintaan Anda berikutnya, apakah Anda menambahkan aturan melalui /permissions atau dengan editing a settings file directly. Itu termasuk aturan yang Anda tambahkan melalui /permissions di tengah putaran.

Ketika tool search aktif, yang merupakan default pada model yang didukung, definisi tool permintaan tidak berubah dan prefiks yang di-cache bertahan. Ketika tool search tidak tersedia atau dinonaktifkan, Claude Code menghapus definisi dari permintaan berikutnya, yang membatalkan cache, dan begitu juga menghapus aturan nanti.

Hanya aturan deny yang cocok di posisi nama-tool yang memblokir tool dengan cara ini: nama tool telanjang, bentuk Bash(*) yang setara, atau tool-name glob seperti "*". Glob yang cocok hanya dengan tool MCP, seperti "mcp__*", memblokir tool-tool itu dengan cara yang sama. Aturan deny yang dibatasi seperti Bash(rm *), dan semua aturan allow dan ask, tidak mengubah tool mana yang Claude lihat. Claude Code memeriksanya ketika Claude mencoba panggilan, meninggalkan prefiks tetap utuh.

Compacting the conversation

Compaction menggantikan riwayat pesan Anda dengan ringkasan. Dengan desain, ini membatalkan lapisan percakapan, karena permintaan berikutnya memiliki riwayat yang lebih baru dan lebih pendek yang tidak berbagi prefiks dengan yang lama. Claude Code menggunakan kembali lapisan system prompt kecuali percakapan resumed while keeping a system prompt that would otherwise have changed; dalam hal itu compaction pertama beralih ke prompt saat ini dan lapisan itu membangun kembali sekali. Ini memuat ulang konteks proyek dari disk, yang cache-hits hanya jika CLAUDE.md dan memory tidak berubah sejak sesi dimulai.

Untuk menghasilkan ringkasan, Claude Code mengirim permintaan terpisah dengan system prompt, tools, dan riwayat yang sama seperti percakapan Anda, ditambah instruksi summarization yang ditambahkan sebagai pesan pengguna final. Saat cache hangat, permintaan itu membaca prefiks Anda dari cache, jadi /compact di tengah sesi biaya sebagian kecil dari apa yang ukuran konteks sarankan dan menghabiskan sebagian besar waktunya menghasilkan ringkasan.

Setelah istirahat lebih lama dari cache lifetime, tidak ada cache yang tersisa untuk dibaca, jadi permintaan summarization memproses ulang riwayat penuh sebagai input yang tidak di-cache. Ini adalah mengapa /compact biaya paling banyak ketika Anda resume an old session. Dalam kedua kasus hangat dan dingin, putaran setelah compaction membangun kembali cache percakapan hanya untuk ringkasan yang jauh lebih pendek, jadi putaran itu bukan bagian yang lambat.

Accumulating many images

API membatasi berapa banyak gambar dan PDF yang dapat dibawa setiap permintaan. Untuk angka saat ini, lihat Request limits dalam dokumentasi API. Claude Code juga membatasi ukuran total gambar dan PDF dalam permintaan, jadi screenshot besar mencapai batas dengan lebih sedikit gambar daripada yang kecil.

Ketika permintaan berikutnya akan melewati salah satu batas, Claude Code menghapus batch gambar dan PDF tertua dari apa yang dikirimnya, yang membuat ruang untuk lebih banyak sebelum perlu menghapus lagi. Claude tidak lagi dapat melihat gambar yang dihapus. Jika Claude membutuhkan salah satu dari mereka lagi, bagikan lagi.

Menghapus gambar mengubah pesan yang menahannya, jadi permintaan berikutnya memproses ulang percakapan dari yang paling awal dari pesan-pesan itu ke depan. Karena Claude Code menghapus batch sekaligus, Anda melihat satu putaran yang lebih lambat per batch daripada satu dengan setiap screenshot baru.

Upgrading Claude Code

Versi Claude Code baru biasanya memperbarui system prompt atau definisi tool, jadi percakapan pertama yang Anda mulai setelah upgrade membangun cache-nya dari atas. Auto-update mengunduh versi baru di latar belakang tetapi menerapkannya pada peluncuran berikutnya, tidak pernah di tengah sesi, jadi Anda melihat ini sebagai putaran pertama yang tidak di-cache setelah restart daripada kejutan selama sesi. Atur DISABLE_AUTOUPDATER=1 untuk mengontrol kapan upgrade diterapkan.

Tindakan yang mempertahankan cache

Tindakan-tindakan ini baik menambahkan ke akhir percakapan atau tidak menyentuh permintaan sama sekali. Beberapa di antaranya, seperti mengedit CLAUDE.md, mempertahankan cache karena alasan yang sama mengapa perubahan tidak mencapai sesi yang sedang berjalan sampai /clear, /compact, atau restart.

• Mengedit file di repositori Anda
• Mengedit CLAUDE.md di tengah sesi
• Mengubah mode izin
• Mengubah gaya output
• Memanggil skills dan commands
• Menjalankan /recap
• Memutar ulang percakapan
• Menjalankan subagent

Mengedit file di repositori Anda

Konten file memasuki konteks hanya ketika Claude membacanya, dan pembacaan menambahkan ke percakapan. Mengedit file yang sebelumnya dibaca Claude tidak secara retroaktif mengubah pembacaan sebelumnya dalam riwayat. Sebaliknya, Claude Code menambahkan <system-reminder> yang mencatat file berubah, dan Claude membacanya kembali jika diperlukan.

Mengedit CLAUDE.md di tengah sesi

File CLAUDE.md tingkat project-root dan user-level Anda dibaca sekali pada awal sesi dan disimpan dalam memori. Mengeditnya di tengah sesi tidak membatalkan cache, tetapi edit juga tidak berlaku. Claude terus bekerja dengan versi yang dimuat pada awal sesi. Konten baru dimuat pada /clear, /compact, atau restart berikutnya.

File CLAUDE.md bersarang di subdirektori dan aturan dengan frontmatter paths: dimuat kemudian, ketika Claude pertama kali membaca file yang cocok. Mengedit satu sebelum dimuat memang berlaku. Setelah dimuat, konten adalah bagian dari riwayat percakapan, jadi edit di tengah sesi tidak secara retroaktif mengubahnya.

Mengubah mode izin

Beralih antara mode izin, seperti dari Manual ke accept edits, tidak mengubah system prompt atau definisi tool, jadi perubahan mode aman untuk cache. Pengecualiannya adalah plan mode dengan pengaturan model opusplan, yang mengalihkan model antara Opus dan Sonnet saat Anda memasuki atau meninggalkan plan mode. Itu membuat toggle mode menjadi model switch.

Mengubah gaya output

Ketika Anda beralih gaya output di tengah sesi dengan /output-style, /config, atau pengaturan outputStyle, Claude menggunakan gaya baru mulai dari pesan Anda berikutnya. Claude Code mengirimkan instruksi gaya baru sebagai pesan dalam percakapan, jadi permintaan itu masih membaca system prompt dan percakapan sebelumnya dari cache.

Sebelum v2.1.251, perubahan gaya di tengah sesi mempertahankan cache tetapi tidak berlaku sampai Anda menjalankan /clear atau memulai sesi baru.

Memanggil skills dan commands

Skills dan commands menyuntikkan instruksi mereka sebagai pesan pengguna pada titik pemanggilan. Tidak ada yang lebih awal dalam percakapan berubah. Skill atau command yang frontmatter-nya menamai model dapat menjadi model switch untuk giliran itu.

Menjalankan `/recap`

/recap menghasilkan ringkasan untuk ditampilkan di terminal Anda. Tidak seperti /compact, ini menambahkan ringkasan sebagai output command daripada mengganti riwayat pesan Anda, jadi prefix yang di-cache tetap utuh.

Memutar ulang percakapan

/rewind memotong percakapan Anda kembali ke giliran sebelumnya. Riwayat yang tersisa adalah konten yang sama yang dibangun cache darinya pada titik itu, dan system prompt serta lapisan konteks proyek tidak berubah, jadi permintaan berikutnya mencapai entri cache yang lebih awal. Setiap giliran sejak saat itu telah membaca melalui prefix itu, yang menjaga entri tetap hangat bahkan jika giliran asli lebih lama dari TTL.

Memulihkan checkpoint file bersama percakapan tidak memiliki efek terpisah pada cache. Konten file memasuki konteks hanya ketika Claude membacanya, sama seperti mengedit file di repositori Anda.

Melanjutkan sesi

Ketika Anda melanjutkan sesi, Claude Code mengirimkan seluruh percakapan lagi, dan permintaan membaca dari cache bagian mana pun dari prefiks yang tidak berubah dan masih dalam masa pakai cache. Tabel lapisan di bagian atas halaman ini mengatakan apa yang berubah di setiap lapisan.

Prompt sistem akan berubah setelah upgrade Claude Code atau dengan teks --append-system-prompt yang berbeda pada resume. Secara default, percakapan yang dilanjutkan mempertahankan prompt sistem yang dimulainya, sehingga riwayatnya masih berada di belakang prompt yang sama, dan perubahan berlaku setelah percakapan dikompakkan atau dalam percakapan baru. Bendera prompt sistem dalam percakapan yang dilanjutkan mencakup kasus di mana Claude Code membangun kembali prompt pada setiap permintaan sebagai gantinya.

Cache lifetime

Prefix yang di-cache kedaluwarsa setelah periode tidak aktif. Setiap permintaan yang mencapai cache mengatur ulang timer, jadi cache tetap hangat selama Anda terus bekerja. Setelah jeda yang cukup lama, permintaan berikutnya menghitung ulang input penuh dan membangun kembali cache, itulah mengapa giliran pertama kembali setelah menjauh dapat terasa jauh lebih lambat.

Pada paket Pro atau Max, ketika Anda melanjutkan sesi besar setelah istirahat lama, Claude Code menawarkan untuk melanjutkan dari ringkasan sehingga permintaan nanti tidak membawa riwayat penuh.

Time to live (TTL) mengontrol berapa lama jeda yang cache bertahan. API menawarkan dua: TTL lima menit, dan TTL satu jam yang menjaga cache tetap hangat melalui istirahat yang lebih lama tetapi menagih penulisan cache dengan tarif lebih tinggi. TTL yang lebih lama membantu ketika Anda meninggalkan sesi idle dan kembali ke sana, karena Anda melewati pemrosesan ulang yang dikenakan prefix yang kedaluwarsa. Ini lebih mahal pada ledakan pekerjaan singkat yang tidak pernah idle melampaui lima menit, di mana tarif penulisan yang lebih tinggi berlaku dan masa pakai cache yang lebih lama tidak digunakan.

TTL mana yang diterima setiap permintaan

Claude Code memutuskan TTL per permintaan, dan setiap permintaan jatuh dalam salah satu dari dua bucket tetap:

• Main conversation: giliran interaktif Anda, run -p non-interaktif, dan giliran Agent SDK, ditambah pembantu yang Claude Code jalankan inline dengan mereka
• Everything else: permintaan yang Claude Code buat di luar percakapan itu, seperti subagents, workflows, teammates dalam proses, fork, compaction, dan judul sesi

Kecuali Anda memilih TTL sendiri, Claude Code meminta TTL satu jam hanya pada langganan Claude dalam penggunaan yang disertakan paket Anda. Di sana ia meminta jam untuk percakapan utama, ditambah serangkaian kecil permintaan pembantu yang Anthropic kontrol di sisi server. Tabel ini memberikan TTL default setiap bucket di bawah kedua jenis penagihan.

Setelah Anda melampaui batas penggunaan paket Anda dan Claude Code menggunakan usage credits, Anda ditagih untuk penggunaan itu, jadi Claude Code menurunkan percakapan utama ke TTL lima menit yang lebih murah. Untuk menjaga TTL satu jam di sana, pilih TTL sendiri.

Pilih TTL sendiri

Anda dapat mengatur TTL untuk salah satu bucket. Setiap kontrol mengambil 5m atau 1h, dan Claude Code mengabaikan nilai lainnya.

• Main conversation: pengaturan promptCacheTtl, atau variabel lingkungan CLAUDE_CODE_PROMPT_CACHE_TTL environment variable
• Everything else: pengaturan subagentPromptCacheTtl, atau variabel lingkungan CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL

Kedua pengaturan dan kedua variabel lingkungan memerlukan Claude Code v2.1.242 atau lebih baru. Jika Anda masuk dengan API key atau menggunakan penyedia cloud, atur promptCacheTtl ke 1h untuk memberikan percakapan utama cache satu jam. Permintaan di luar itu menjaga default lima menit sampai Anda memilih TTL untuk bucket itu juga.

Ketika lebih dari satu kontrol berlaku, Claude Code mengambil kecocokan pertama dalam urutan ini:

1. FORCE_PROMPT_CACHING_5M=1, yang memaksa lima menit untuk kedua bucket
2. Variabel lingkungan bucket
3. Pengaturan bucket
4. Untuk permintaan subagent, nilai cacheTtl dalam field frontmatter experimental subagent, yang memerlukan Claude Code v2.1.248 atau lebih baru. Claude Code mengabaikan 1h di sana sementara langganan Claude Anda menggunakan usage credits
5. ENABLE_PROMPT_CACHING_1H=1, yang meminta satu jam untuk kedua bucket
6. Default untuk bucket permintaan

Atur FORCE_PROMPT_CACHING_5M=1 ketika Anda men-debug perilaku cache, membandingkan dua TTL, atau mengganti TTL yang lebih lama yang ditetapkan dalam managed settings.

Untuk mengonfirmasi TTL mana yang digunakan penulisan cache percakapan utama Anda, jalankan claude -p "hello" --output-format json dan baca usage.cache_creation dalam hasilnya. Claude Code melaporkan penulisan cache satu jam di bawah ephemeral_1h_input_tokens dan penulisan cache lima menit di bawah ephemeral_5m_input_tokens.

Melalui gateway LLM yang Anda atur dengan ANTHROPIC_BASE_URL, bagian dari permintaan satu jam bepergian dalam header anthropic-beta, jadi konfigurasikan gateway untuk meneruskan header itu tanpa perubahan. TTL satu jam tidak tersedia melalui gateway aplikasi Claude. Di Amazon Bedrock, dukungan prompt caching, panjang prefix yang dapat di-cache minimum, dan ketersediaan TTL satu jam semuanya bervariasi menurut model. Jika hitungan token cache tetap di nol, periksa model yang didukung, wilayah, dan batas dalam dokumentasi Amazon Bedrock.

Cakupan cache

Di Claude Code, cache secara efektif dicakup ke satu mesin dan direktori. Setiap percakapan membawa direktori kerja, platform, shell, dan versi OS, dan prompt sistem menamai jalur auto-memory Anda, jadi dua sesi di direktori berbeda membangun prefix berbeda dan melewatkan cache satu sama lain. Itu termasuk worktrees dari repositori yang sama, karena setiap worktree memiliki direktori kerjanya sendiri.

Sesi yang Anda jalankan secara paralel di direktori yang sama membangun prefix yang cocok dan membaca cache satu sama lain. Sesi berurutan berbagi prefix hanya ketika snapshot status git yang diambil pada startup cocok, karena setiap percakapan juga membawa cabang dan commit terbaru dari snapshot itu.

Cache API yang mendasarinya lebih luas. Cache diisolasi di antara organisasi, dan pada beberapa penyedia, di antara workspace dalam organisasi. Dalam batas-batas itu, setiap dua permintaan dengan model dan prefix yang sama membaca cache yang sama. Untuk pemanggil Agent SDK yang menjalankan armada proses otomatis, lihat improve prompt caching across users and machines untuk menekan bagian per-mesin dari prompt sistem dan berbagi cache di seluruh mesin.

Periksa kinerja cache

Kinerja cache muncul sebagai dua hitungan token yang dilaporkan API pada setiap respons. Cara paling langsung untuk menontonnya secara langsung adalah statusline script yang membaca objek current_usage:

Rasio baca-ke-kreasi yang tinggi berarti caching berfungsi dengan baik. Jika kreasi tetap tinggi giliran demi giliran, sesuatu berubah dalam prefix Anda. Bagian actions that invalidate the cache mencantumkan penyebab umum.

Untuk ringkasan per-sesi, jalankan /usage. Setelah respons pertama percakapan utama, Claude Code menambahkan baris Prompt cache (main) ke blok Sesi, menampilkan rasio hit sesi, jumlah miss, dan apakah cache sedang hangat sekarang. Skrip statusline dapat membaca angka yang sama dari objek prompt_cache. Keduanya memerlukan Claude Code v2.1.251 atau lebih baru.

Baris Prompt cache (main) juga menamai kemungkinan penyebab miss terakhir ketika Claude Code dapat mengidentifikasinya, misalnya likely cause: tool definitions changed. Teks kemungkinan-penyebab memerlukan Claude Code v2.1.260 atau lebih baru.

Untuk visibilitas di seluruh organisasi, exporter OpenTelemetry melaporkan token baca dan kreasi cache per pengguna dan sesi. Lihat Monitor usage untuk referensi metrik dan atribut acara.

Subagents dan cache

Subagent memulai percakapannya sendiri dengan prompt sistem dan set alat-nya sendiri, terpisah dari induk. Permintaan pertamanya tidak membaca cache induk, karena kedua prefix berbeda, dan itu menghangatkan cache-nya sendiri di seluruh giliran-nya. Subagents berada di luar bucket TTL percakapan utama, jadi mereka mendapatkan lima menit bahkan pada langganan sampai Anda memilih yang lebih lama.

Cache induk tidak terpengaruh. Dari sisi induk, panggilan dan hasil subagent ditambahkan ke percakapan, meninggalkan prefix induk utuh.

Fork, sebaliknya, mewarisi prompt sistem induk, alat, dan riwayat percakapan dengan tepat, jadi permintaan pertamanya membaca cache induk.

Permintaan lain juga dapat membaca prefix yang di-cache oleh permintaan sebelumnya:

• Session copies: sesi yang Anda salin dengan /fork menerima instruksi isolasinya sebagai pesan di akhir percakapan yang disalin, jadi cache yang dibangun oleh percakapan asli tetap utuh.
• Compaction: panggilan summarisasi yang dijelaskan dalam Compacting the conversation menggunakan pendekatan berbagi prefix yang sama.
• Resumed subagents: ketika Claude melanjutkan subagent, permintaan pertama dari run yang dilanjutkan dapat membaca cache yang di-hangatkan oleh run asli.
• Workflow fan-outs: dalam workflow fan-out dari agen dengan prefix yang sama, Claude Code menahan semua kecuali yang pertama selama hingga 5 detik secara default, jadi permintaan pertama mereka dapat membaca prefix yang di-cache oleh agen pertama.

Nonaktifkan prompt caching

Menonaktifkan caching kadang-kadang berguna saat men-debug perilaku caching dengan model atau penyedia tertentu. Untuk mematikannya, atur salah satu variabel lingkungan ini ke 1:

Untuk menetapkan kebijakan caching di seluruh organisasi, masukkan salah satu dari ini atau TTL variables dalam blok env dari managed settings. Untuk penggunaan normal, biarkan caching diaktifkan.

Sumber daya terkait

• Lessons from building Claude Code: Prompt caching is everything: alasan desain untuk plan mode, deferred tool loading, dan compaction
• Explore the context window: apa yang dimuat ke konteks dan kapan
• Reduce token usage: strategi di luar caching untuk mengelola ukuran konteks
• Track and reduce costs: pelacakan token cache dan konfigurasi TTL untuk pemanggil Agent SDK
• Prompt caching: mekanisme API yang mendasarinya, breakpoints, dan pricing