Jalankan Claude Code secara programatis

Agent SDK memberikan Anda alat yang sama, loop agen, dan manajemen konteks yang mendukung Claude Code. Tersedia sebagai CLI untuk skrip dan CI/CD, atau sebagai paket Python dan TypeScript untuk kontrol programatis penuh. Untuk menjalankan Claude Code dalam mode non-interaktif, berikan -p dengan prompt Anda dan opsi CLI apa pun yang Anda butuhkan:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Halaman ini mencakup penggunaan Agent SDK melalui CLI (claude -p). Untuk paket SDK Python dan TypeScript dengan output terstruktur, callback persetujuan alat, dan objek pesan asli, lihat dokumentasi Agent SDK lengkap.

Penggunaan dasar

Tambahkan flag -p (atau --print) ke perintah claude apa pun untuk menjalankannya secara non-interaktif. Tidak semua opsi CLI menggabung dengan -p. Claude Code menolak --bg, dan menolak --cloud dengan deskripsi tugas, dengan kesalahan yang menyebutkan konflik; --cloud dengan ID sesi dan -p sebagai gantinya antrian pesan ke sesi cloud tersebut dan keluar. Opsi yang akan Anda gabungkan dengan -p sering kali mencakup:

--continue untuk melanjutkan percakapan
--allowedTools untuk persetujuan otomatis tool
--output-format untuk output terstruktur

Contoh ini menanyakan Claude tentang basis kode Anda dan mencetak respons:

claude -p "What does the auth module do?"

Claude Code keluar dengan kode 0 saat berhasil dan kode bukan nol ketika jalankan gagal, sehingga skrip Anda dapat bercabang pada status keluar. Jika Anda melewatkan flag yang tidak valid, Claude Code melaporkan kesalahan ke stderr sebelum jalankan dimulai. Ketika kegagalan terjadi di dalam jalankan, seperti autentikasi yang hilang, Claude Code mencetak kegagalan sebagai hasil pada stdout.

Mulai lebih cepat dengan bare mode

Tambahkan --bare untuk mengurangi waktu startup dengan melewati penemuan otomatis hooks, skills, perintah kustom, subagents, plugins yang diinstal, server MCP, auto memory, dan CLAUDE.md. Tanpanya, claude -p menemukan dan memuat semuanya seperti yang dilakukan sesi interaktif, termasuk apa pun yang dikonfigurasi di direktori kerja atau ~/.claude. Bare mode berguna untuk CI dan skrip di mana Anda memerlukan hasil yang sama di setiap mesin. Hook di ~/.claude rekan kerja atau server MCP di .mcp.json proyek tidak akan berjalan, karena bare mode tidak pernah membacanya. Direktori yang Anda beri nama dengan --add-dir adalah pengecualian parsial: bare mode memuat skills dari folder .claude/skills/ nya, tetapi masih melewati folder .claude/commands/ dan .claude/agents/ nya. Skills dari direktori tambahan mencakup apa yang dimuat dan tidak dimuat. Tanpa --bare, sesi -p menjalankan hooks di .claude/settings.json proyek dan menghubungkan server di .mcp.json nya, bahkan di folder yang belum pernah Anda percayai. Sesi -p tidak menampilkan dialog kepercayaan workspace dan tidak ada permintaan persetujuan per-server. Apa yang berjalan sebelum Anda mempercayai folder mencakup setiap jenis konten repositori di bawah -p dan cara menjaganya tetap keluar. Contoh ini menjalankan tugas ringkasan sekali pakai dalam bare mode dan pra-menyetujui tool Read sehingga panggilan selesai tanpa permintaan izin. Atur ANTHROPIC_API_KEY sebelum menjalankannya, karena bare mode tidak menggunakan login langganan Anda:

claude --bare -p "Summarize README.md" --allowedTools "Read"

Dalam bare mode, Claude Code tidak pernah membaca kredensial OAuth atau keychain sistem. Untuk Anthropic API, atur ANTHROPIC_API_KEY di lingkungan, dengan kunci yang dibuat di Claude Console, atau berikan apiKeyHelper di JSON --settings. Amazon Bedrock, Google Cloud’s Agent Platform, dan Microsoft Foundry terus membaca kredensial penyedia mereka sendiri seperti biasanya. Dalam bare mode Claude memiliki akses ke tool Bash, pembacaan file, dan pengeditan file. Berikan konteks apa pun yang Anda butuhkan dengan flag:

Untuk memuat	Gunakan
Penambahan system prompt	`--append-system-prompt`, `--append-system-prompt-file`
Pengaturan	`--settings <file-or-json>`
Server MCP	`--mcp-config <file-or-json>`
Agent kustom	`--agents <file-or-json>`
Plugin	`--plugin-dir <path>`, `--plugin-url <url>`

Bare mode juga membatasi apa yang terjadi selama sesi berjalan:

Server MCP: hanya server yang diberikan di baris perintah yang terhubung, misalnya dengan --mcp-config. Dalam sesi interaktif, Claude Code juga melewati koneksi IDE otomatis kecuali Anda meneruskan --ide.
System reminder: Claude menerima prompt Anda dan hasil tool tanpa system reminder yang biasanya ditambahkan Claude Code bersamanya. Misalnya, Claude tidak diberi tahu ketika file yang dibacanya sebelumnya berubah di disk, dan Claude tidak mendapatkan daftar skill yang tersedia, termasuk skill dari folder --add-dir.
Tugas latar belakang: tidak ada yang berjalan. Perintah yang mencapai timeout berhenti alih-alih berpindah ke latar belakang.

Sebelum v2.1.286, batasan ini hanya berlaku sebagian: sesi --bare interaktif menghubungkan server MCP yang akan dihubungkan oleh sesi normal, setiap sesi --bare mengirim system reminder, dan tugas latar belakang tetap tersedia.

--bare adalah mode yang direkomendasikan untuk panggilan skrip dan SDK, dan akan menjadi default untuk -p di rilis mendatang.

Tugas latar belakang saat keluar

Setelah Claude menyelesaikan gilirannya dan stdin telah ditutup, eksekusi claude -p dapat tetap terbuka untuk menunggu pekerjaan latar belakang yang dimulai Claude. Kecuali perintah latar belakang yang dimulai oleh percakapan utama masih berjalan, secara default Claude Code menghentikan apa pun yang masih berjalan setelah 10 menit menunggu dalam keadaan idle secara berkelanjutan dan membuang hasil parsialnya. Untuk mengubah batas 10 menit tersebut, atur CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, atau atur ke 0 untuk menunggu tanpa batas. Eksekusi menunggu pekerjaan latar belakang seperti perintah latar belakang, subagent dan workflow, watch Monitor, serta wakeup /loop yang tertunda:

Perintah latar belakang: untuk perintah yang dimulai oleh percakapan utama, misalnya server dev atau build watch, eksekusi menunggu hingga perintah tersebut keluar atau mencapai batas waktunya. Claude kemudian mengambil satu giliran lagi dengan hasilnya. Selama perintah berjalan, batas 10 menit tidak mengakhiri penantian.
Subagent dan workflow latar belakang: eksekusi tetap terbuka hingga pekerjaan tersebut selesai, karena hasilnya adalah bagian dari output akhir.
Watch Monitor: eksekusi menunggu hingga watch mencapai timeout atau batas 10 menit mengakhiri penantian, mana pun yang terjadi lebih dulu. Selama menunggu, Claude terus merespons apa yang dilaporkan watch. Secara default, watch mencapai timeout lima menit setelah Claude memulainya.
Wakeup yang tertunda: dalam eksekusi yang prompt-nya Anda berikan sebagai teks alih-alih dengan --input-format stream-json, ketika Claude telah menjadwalkan wakeup /loop dengan tempo sendiri, eksekusi menunggu setiap wakeup terpicu dan menjalankan iterasinya hingga loop berakhir, bahkan melewati batas 10 menit.

Ketika stderr adalah terminal dan eksekusi telah menunggu selama lima detik, Claude Code mencetak satu baris ke stderr yang diawali dengan Waiting for background work to finish dan menyebutkan pekerjaan tersebut. Dengan output json atau stream-json, baris tersebut hanya dicetak ketika stdout bukan terminal, sehingga JSON yang dibaca skrip Anda tidak pernah memuatnya. Jika eksekusi mencapai batas --max-budget-usd, Claude Code menghentikan pekerjaan latar belakang yang tersisa alih-alih menunggu. Ketika pekerjaan latar belakang memulai giliran lain, eksekusi mencetak hasil setiap giliran dengan output text default dan hasil giliran terakhir dengan output json. Sebelum v2.1.295, eksekusi juga hanya mencetak hasil giliran terakhir dengan output text.

Hentikan jalankan dengan SIGTERM

Jika Anda menghentikan jalankan claude -p dengan SIGTERM, misalnya dengan kill atau dari pengawas proses, Claude Code keluar dengan kode 143. Claude Code meninggalkan giliran yang sedang berlangsung tidak selesai dan tidak mencatat hasil untuknya. Untuk mengakhiri giliran sebagai gantinya, kirim SIGINT, atau panggil interrupt() Agent SDK, sebelum Anda menghentikan proses. Pada SIGTERM, Claude Code menghentikan pohon proses dari perintah Bash apa pun yang masih berjalan. Claude Code kemudian menjalankan SessionEnd hooks dan keluar. Saat keluar, Claude Code tidak memulai panggilan tool baru, tidak mengirim permintaan model baru, dan tidak menjalankan hook selain SessionEnd. Jika jalankan berada di tengah perintah atau menunggu permintaan izin ketika sinyal tiba, Claude Code menangani langkah itu sebagai berikut:

Menjalankan perintah: Claude Code mencatat perintah sebagai terbunuh dalam sesi.
Menunggu jawaban untuk permintaan izin: jika Anda mengirim SIGTERM ke proses, Claude Code meninggalkan permintaan tersebut tanpa jawaban. Jika program Anda menutup sesi melalui Agent SDK, SDK mengakhiri input Claude Code sebelum mengirim sinyal apa pun, dan Claude Code membatalkan permintaan tersebut segera setelah input berakhir.

Ketika Anda melanjutkan sesi, Claude Code meninggalkan giliran yang terputus seperti apa adanya, dan prompt berikutnya Anda mendorong percakapan. Untuk membuat Claude Code melanjutkan giliran yang terputus saat resume, atur CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Jika direktori kerja dihapus

Jika direktori kerja dari sesi claude -p atau Agent SDK dihapus di tengah sesi, sesi terus berjalan. Ketika giliran dimulai sementara direktori hilang, Claude Code mengeluarkan pesan peringatan dalam output stream-json, dan perintah shell gagal sampai direktori ada lagi.

Contoh

Contoh-contoh ini menyoroti pola CLI umum. Jika perintah menamai file seperti auth.py atau build-error.txt, gantikan dengan file dari proyek Anda sendiri. Dalam CI atau lingkungan skrip lainnya, tambahkan --bare sehingga Claude Code dimulai tanpa memuat hooks, plugins, auto memory, atau CLAUDE.md host.

Saluran data melalui Claude

Mode non-interaktif membaca stdin, sehingga Anda dapat menyalurkan data dan mengarahkan respons keluar seperti alat baris perintah lainnya. Contoh ini menyalurkan log build ke Claude dan menulis penjelasan ke file:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Dengan --output-format json, payload respons mencakup total_cost_usd dan rincian biaya per-model, sehingga pemanggil skrip dapat melacak pengeluaran tanpa berkonsultasi dengan dashboard penggunaan. Ketika Anda melanjutkan percakapan sebelumnya dengan --continue atau --resume, jalankan melaporkan total keseluruhan percakapan, pengeluaran jalankan sebelumnya disertakan. Kedua angka tersebut adalah perkiraan sisi klien dan dapat berbeda dari tagihan aktual Anda.

Stdin yang disalurkan dibatasi pada 10MB. Jika Anda melampaui batas, Claude Code keluar dengan kesalahan yang jelas dan status bukan nol. Untuk bekerja dengan input yang lebih besar, tulis konten ke file dan referensikan jalur file dalam prompt Anda alih-alih menyalurkannya.

Jika Claude Code tidak dapat membaca stdin, misalnya karena proses yang memulainya memutuskan ujungnya, Claude Code mencetak peringatan ke stderr dan melanjutkan dengan prompt dari baris perintah. Sebelum v2.1.211, stdin yang tidak dapat dibaca di Windows menghancurkan sesi atau membuatnya keluar diam-diam tanpa output.

Tambahkan Claude ke skrip build

Anda dapat membungkus panggilan non-interaktif dalam skrip untuk menggunakan Claude sebagai linter atau reviewer khusus proyek. Skrip package.json ini menyalurkan diff terhadap main ke Claude dan memintanya untuk melaporkan typo. Menyalurkan diff berarti Claude tidak memerlukan izin Bash untuk membacanya, dan tanda kutip ganda yang di-escape menjaga skrip portabel ke Windows:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Jalankan dengan npm run lint:claude.

Dapatkan output terstruktur

Gunakan --output-format untuk mengontrol bagaimana respons dikembalikan:

text (default): output teks biasa
json: JSON terstruktur dengan hasil, ID sesi, dan metadata
stream-json: JSON yang dibatasi baris baru untuk streaming real-time

Contoh ini mengembalikan ringkasan proyek sebagai JSON dengan metadata sesi, dengan hasil teks di bidang result:

claude -p "Summarize this project" --output-format json

Untuk mendapatkan output yang sesuai dengan skema tertentu, gunakan --output-format json dengan --json-schema dan definisi JSON Schema. Respons mencakup metadata tentang permintaan (ID sesi, penggunaan, dll.) dengan output terstruktur di bidang structured_output. Contoh ini mengekstrak nama fungsi dan mengembalikannya sebagai array string:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Jika nilainya bukan JSON Schema yang valid, claude keluar dengan Error: --json-schema is not a valid JSON Schema diikuti oleh diagnostik validator. Claude Code menerima skema yang menggunakan kata kunci format, seperti "format": "email", tetapi memperlakukan format sebagai anotasi dan tidak memberlakukannya.

Gunakan alat seperti jq untuk mengurai respons dan mengekstrak bidang tertentu:

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Stream respons

Gunakan --output-format stream-json dengan --verbose dan --include-partial-messages untuk menerima token saat dihasilkan. Setiap baris adalah objek JSON yang mewakili acara:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

Baris terakhir dari stream adalah pesan result dengan teks respons akhir, biaya, dan metadata sesi. Jika konsumen Anda membaca stream dengan lambat, Claude Code menunggu output yang antri untuk terkuras sebelum keluar, menskalakan waktu tunggu dengan berapa banyak yang masih antri, dibatasi pada 30 detik. Sebelum v2.1.214 waktu tunggu keluar dibatasi pada sekitar dua detik, yang dapat memotong akhir respons besar. Contoh berikut menggunakan jq untuk memfilter delta teks dan menampilkan hanya teks streaming. Flag -r menampilkan string mentah (tanpa tanda kutip) dan -j bergabung tanpa baris baru sehingga token streaming terus menerus:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Untuk streaming programatis dengan callback dan objek pesan, lihat Stream responses in real-time dalam dokumentasi Agent SDK.

Ikuti pesan subagent

Pesan dari subagent dan dari skill yang berjalan dalam subagent muncul dalam stream sebagai pesan assistant dan user. Bidang parent_tool_use_id pada pesan tersebut menunjukkan eksekusi mana yang memiliki setiap pesan. Pesan dari percakapan utama membawa null di bidang itu. Pesan pertama dari forked skill, atau dari subagent yang berjalan di foreground, adalah pesan user yang membawa prompt atau konten skill yang mendorongnya. Setelah pesan pertama itu, Claude Code memancarkan:

Secara default: blok tool_use dan tool_result dari eksekusi tersebut.
Dengan --forward-subagent-text atau CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: blok teks dan thinking dari eksekusi tersebut juga, sehingga Anda dapat merekonstruksi transkrip setiap eksekusi.

Ketika Anda mengaktifkan salah satu opsi, Claude Code meneruskan pesan dari subagent di setiap kedalaman nesting, baik masing-masing dibuat dengan tool Agent maupun dimulai sebagai forked skill. Di parent_tool_use_id, pesan subagent bersarang membawa ID dari panggilan tool Agent atau Skill yang memulainya, sehingga Anda dapat membangun kembali pohon nesting penuh dengan mengikuti ID tersebut. Eksekusi yang dimulai Claude dengan panggilan tool membawa ID panggilan tool tersebut. Forked skill yang Anda mulai dengan memberikan /<skill-name> sebagai prompt tidak memiliki panggilan tool, sehingga pesannya membawa nilai forked-command- sebagai gantinya dan tiba setelah skill tersebut selesai. Temukan cara eksekusi dimulai di kolom pertama:

Cara eksekusi dimulai	`parent_tool_use_id`	Kapan pesannya tiba
Claude memanggil tool Agent dari percakapan utama	ID dari blok `tool_use` Agent tersebut	Selama subagent bekerja
Claude memanggil tool Skill untuk forked skill dari percakapan utama	ID dari blok `tool_use` Skill tersebut	Selama forked skill bekerja
Anda memberikan `/<skill-name>` sebagai prompt	Nilai yang dimulai dengan `forked-command-`	Bersamaan dan berurutan setelah forked skill selesai

Untuk forked skill yang dimulai dari prompt, cocokkan parent_tool_use_id pada awalan forked-command-, karena nama setelahnya dapat berbeda dari yang Anda ketik. Jika sebagian pesan ini tidak ada di stream Anda, periksa versi Claude Code Anda terhadap versi minimum berikut:

--forward-subagent-text dan CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: v2.1.211 atau lebih baru
Penerusan di setiap kedalaman nesting: v2.1.219 atau lebih baru
Forked skill yang dimulai Claude dengan tool Skill dari percakapan utama: v2.1.86 atau lebih baru untuk blok tool_use dan tool_result-nya, dan v2.1.265 atau lebih baru untuk pesan user pertamanya serta blok teks dan thinking-nya
Pesan subagent yang dibuat oleh forked skill, dan pesan forked skill yang dimulai di dalam subagent atau forked skill lainnya: v2.1.275 atau lebih baru
Pesan forked skill yang Anda mulai dengan memberikan /<skill-name> sebagai prompt: v2.1.287 atau lebih baru

Tangani retry API

Ketika permintaan API gagal dengan kesalahan yang dapat dicoba ulang, Claude Code memancarkan acara system/api_retry sebelum mencoba ulang. Pada v2.1.246 atau lebih baru, ketika 401 atau 403 menolak kredensial apiKeyHelper, Claude Code melakukan dua retry pertama secara diam-diam tanpa acara, kemudian memancarkan acara seperti biasa mulai dari retry berturut-turut ketiga dan seterusnya. Retry diam-diam tersebut tetap dihitung dalam attempt. Anda dapat menggunakan acara ini untuk menampilkan kemajuan retry di antarmuka Anda sendiri.

Bidang	Tipe	Deskripsi
`type`	`"system"`	tipe pesan
`subtype`	`"api_retry"`	mengidentifikasi ini sebagai acara retry
`attempt`	integer	nomor percobaan saat ini, dimulai dari 1
`max_retries`	integer	total retry yang diizinkan untuk penyebab kegagalan ini
`retry_delay_ms`	integer	milidetik hingga percobaan berikutnya
`error_status`	integer atau null	kode status HTTP dari percobaan yang gagal, atau `null` ketika percobaan tidak mendapat respons HTTP dari API
`no_response`	object, opsional	hadir hanya ketika percobaan yang gagal tidak mendapat header respons tepat waktu. `waited_ms` adalah berapa lama percobaan itu menunggu dan `retry_wait_ms` adalah berapa lama retry akan menunggu. Memerlukan Claude Code v2.1.261 atau lebih baru
`error`	string	kategori kesalahan: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, atau `unknown`
`uuid`	string	pengidentifikasi acara unik
`session_id`	string	sesi yang dimiliki acara

Baca metadata sesi

Acara system/init melaporkan metadata sesi termasuk model, tool, server MCP, dan plugin yang dimuat. Ini adalah acara pertama dalam stream kecuali acara startup mendahuluinya:

Acara plugin_install, ketika CLAUDE_CODE_SYNC_PLUGIN_INSTALL diatur.
Acara hook_started, hook_progress, dan hook_response, saat hook SessionStart atau Setup yang dikonfigurasi berjalan. Acara ini di-stream saat hook menghasilkannya.

Acara ini juga membawa array capabilities opsional dari string yang menamai perilaku protokol yang diimplementasikan versi Claude Code ini, seperti interrupt_receipt_v1 atau interrupt_cancel_queued_v1. Periksanya untuk mendeteksi fitur alih-alih membandingkan string versi, dan abaikan nilai yang tidak Anda kenali. Lihat SDKSystemMessage untuk daftar kemampuan.

Gagalkan CI ketika plugin atau server MCP tidak dimuat

Gunakan bidang plugin dalam acara system/init untuk menangkap plugin yang tidak dimuat:

Bidang	Tipe	Deskripsi
`plugins`	array	plugin yang berhasil dimuat, masing-masing dengan `name` dan `path`
`plugin_errors`	array	kesalahan waktu muat plugin, masing-masing dengan `plugin`, `type`, dan `message`. Mencakup versi dependensi yang tidak terpenuhi dan kegagalan muat `--plugin-dir` seperti jalur yang hilang atau arsip yang tidak valid. Plugin yang tidak dimuat tidak ada di `plugins`. Kunci dihilangkan ketika tidak ada kesalahan

Ketika direktori --plugin-dir atau arsip itu sendiri gagal dimuat, entri plugin_errors-nya mencakup jalur absolut yang diselesaikan sebagai path. Gunakan untuk membedakan mana dari beberapa nilai --plugin-dir yang gagal. Bidang path memerlukan Claude Code v2.1.283 atau lebih baru. Gunakan bidang server MCP dengan cara yang sama. Ketika Anda memberikan --mcp-config dengan -p, Claude Code menunggu server yang masih tertunda sebelum menjalankan giliran pertama, hingga timeout startup MCP_TIMEOUT, 30 detik secara default. Server jarak jauh dengan daftar tool yang di-cache melewati penantian, menampilkan pending di system/init, dan terhubung pada panggilan tool pertamanya. Dalam lingkungan self-hosted, penantian yang lebih singkat berlaku sebagai gantinya. Penantian ini memerlukan Claude Code v2.1.221 atau lebih baru. Claude Code memvalidasi setiap entri --mcp-config pada startup dan melewati entri yang gagal validasi, misalnya entri url tanpa type. Jalankan berlanjut dan keluar dengan bersih, jadi periksa bidang ini untuk menangkap server yang tidak pernah dimuat:

Bidang	Tipe	Deskripsi
`mcp_servers`	array	server MCP dalam sesi, masing-masing dengan `name` dan `status`
`mcp_server_errors`	array	entri `--mcp-config` yang dilewati oleh validasi konfigurasi, masing-masing dengan `name`, `type`, dan `message`. `type` adalah kategori lewati seperti `unknown_type`, `url_missing_type`, `invalid_config`, atau `reserved_name`; perlakukan nilai yang tidak Anda kenali sebagai lewati generik. Server yang terpengaruh tidak ada di `mcp_servers`. Kunci dihilangkan ketika tidak ada kesalahan, jadi gerbang CI dapat gagal pada array yang tidak kosong. Memerlukan Claude Code v2.1.219 atau lebih baru

Ketika Anda menjalankan perintah dengan tangan di terminal, Claude Code juga mencetak peringatan startup ke stderr, seperti Warning: 1 MCP server skipped due to invalid config:, diikuti oleh alasan untuk setiap entri yang dilewati. Ketika Anda mengarahkan stderr, atau ketika program seperti runner CI atau host SDK menangkapnya, Claude Code tidak mencetak peringatan dan melaporkan entri yang dilewati hanya di bidang mcp_server_errors. Peringatan memerlukan Claude Code v2.1.219 atau lebih baru.

Lacak pemasangan plugin

Ketika CLAUDE_CODE_SYNC_PLUGIN_INSTALL diatur, Claude Code memancarkan acara system/plugin_install saat plugin marketplace dipasang sebelum giliran pertama. Gunakan ini untuk menampilkan kemajuan pemasangan di UI Anda sendiri.

Bidang	Tipe	Deskripsi
`type`	`"system"`	tipe pesan
`subtype`	`"plugin_install"`	mengidentifikasi ini sebagai acara pemasangan plugin
`status`	`"started"`, `"installed"`, `"failed"`, atau `"completed"`	`started` dan `completed` membatasi pemasangan keseluruhan; `installed` dan `failed` melaporkan marketplace individual
`name`	string, opsional	nama marketplace, hadir pada `installed` dan `failed`
`error`	string, opsional	pesan kegagalan, hadir pada `failed`
`uuid`	string	pengidentifikasi acara unik
`session_id`	string	sesi yang dimiliki acara

Persetujuan otomatis tool

Gunakan --allowedTools untuk membiarkan Claude menggunakan tool tertentu tanpa meminta persetujuan. Mencantumkan Read dan Edit memungkinkan Claude membaca dan mengedit file tanpa meminta izin, kecuali pembacaan dari jalur jaringan. Mencantumkan Bash melakukan hal yang sama untuk perintah shell, kecuali dalam jalankan yang dimulai dalam auto mode, di mana Claude Code menghapus entri Bash polos sebagai aturan allow yang luas dan auto mode mengevaluasi setiap perintah sebagai gantinya. Contoh ini menjalankan suite pengujian dan memperbaiki kegagalan dengan ketiga tool tersebut tercantum:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Untuk menetapkan baseline untuk seluruh sesi alih-alih mencantumkan tool individual, berikan mode izin. Jalankan di mana tidak ada yang menetapkan mode izin mengambil mode izin awal bawaan, yang dapat berupa auto, jadi berikan yang Anda inginkan:

auto: berikan --permission-mode auto agar pengklasifikasi meninjau sebagian besar tindakan alih-alih Anda
dontAsk: Claude Code menolak setiap panggilan yang sebaliknya akan memunculkan permintaan izin, yang berguna untuk jalankan CI yang terkunci. Tindakan yang tidak memerlukan persetujuan dalam mode Manual tetap berjalan, seperti pembacaan file di direktori kerja Anda dan set perintah read-only, begitu juga tindakan yang dicakup oleh entri --allowedTools Anda atau aturan permissions.allow. AskUserQuestion, tool konektor yang diatur organisasi Anda ke ask, tool MCP yang ditandai requiresUserInteraction, dan pembacaan dari jalur jaringan ditolak bahkan ketika aturan allow cocok
acceptEdits: Claude menulis file tanpa meminta persetujuan, dan Claude Code menyetujui secara otomatis perintah filesystem umum seperti mkdir, touch, mv, dan cp. Tindakan yang tidak disetujui otomatis oleh mode mana pun tetap berlaku. Selain set perintah read-only, perintah shell lainnya dan permintaan jaringan masih memerlukan entri --allowedTools atau aturan permissions.allow. Lihat apa yang disetujui otomatis oleh acceptEdits untuk daftar lengkap

Contoh ini menerapkan perbaikan lint dengan acceptEdits sebagai baseline:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Matikan permintaan izin dalam jalankan tanpa pengawasan

Berikan --permission-prompts none ketika tidak ada yang tersedia untuk menjawab permintaan izin, misalnya dalam pekerjaan terjadwal. Flag ini paling penting ketika jalankan Anda memiliki host izin: aplikasi Agent SDK dengan callback canUseTool, atau tool MCP yang Anda berikan dengan --permission-prompt-tool. Tanpa flag ini, jalankan Anda menunggu host itu menjawab setiap permintaan izin. Dengan flag ini, jalankan Anda tidak berkonsultasi dengan host atau menunggunya. Apa pun yang akan memunculkan permintaan izin ditolak kecuali hook PermissionRequest mengizinkannya, Claude diberi tahu bahwa tidak ada yang dapat menyetujui permintaan tersebut dan agar tidak mencobanya ulang, dan jalankan berlanjut. Dalam jalankan -p tanpa host, permintaan ini tetap ditolak, dan flag ini juga memberi tahu Claude agar tidak mencobanya ulang. Aturan izin, hook PermissionRequest, dan mode izin yang Anda atur tetap memutuskan setiap panggilan terlebih dahulu; Claude Code hanya menolak permintaan yang tidak diselesaikan oleh hal lain. Contoh ini menjalankan tugas tanpa pengawasan dalam auto mode. Pengklasifikasi meninjau setiap tindakan seperti biasa, dan Claude Code menolak apa pun yang akan jatuh kembali ke permintaan izin:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Dengan --permission-prompts none, Claude Code menghapus tool yang memerlukan jawaban dari seseorang, seperti AskUserQuestion, sehingga Claude tidak dapat memanggilnya. Setiap permintaan elicitation MCP yang tidak dijawab oleh hook Elicitation dibatalkan. Dengan --output-format stream-json, penolakan muncul sebagai pesan sistem permission_denied, dan pesan hasil akhir mencantumkannya di permission_denials.

Flag --permission-prompts memerlukan Claude Code v2.1.259 atau lebih baru. Versi sebelumnya menolaknya dengan kesalahan opsi tidak dikenal.

Buat commit

Contoh ini meninjau perubahan yang di-stage dan membuat commit dengan pesan yang sesuai:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Flag --allowedTools menggunakan sintaks aturan izin. * di akhir memungkinkan pencocokan awalan, jadi Bash(git diff *) mengizinkan perintah apa pun yang dimulai dengan git diff. Spasi sebelum * penting: tanpanya, Bash(git diff*) juga akan cocok dengan git diff-index.

Dukungan perintah berbeda dalam mode -p:

Skills yang dipanggil pengguna dan perintah kustom berfungsi. Sertakan /skill-name dalam string prompt dan Claude Code memperluasnya sebelum menjalankan.
Perintah bawaan yang hanya berjalan di antarmuka terminal, seperti /login, tidak tersedia.
/model, /effort, /fast, /color, dan /rename menerima nilai sebagai argumen, misalnya /model sonnet, dan /mcp tanpa argumen mencetak ringkasan teks status server. Bentuk-bentuk ini mengikuti catatan ketersediaan setiap perintah.
Untuk mengubah pengaturan, berikan key=value ke /config, misalnya /config thinking=false.
/output-style <style> beralih gaya output dan /output-style saja mencantumkannya. Memerlukan Claude Code v2.1.269 atau lebih baru.

Sesuaikan system prompt

Gunakan --append-system-prompt untuk menambahkan instruksi sambil mempertahankan perilaku default Claude Code. Contoh ini menyalurkan diff PR ke Claude dan menginstruksikannya untuk meninjau kerentanan keamanan. Simpan sebagai skrip shell, misalnya review.sh:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Dalam skrip, "$1" mewakili argumen pertama yang Anda berikan di baris perintah. Jalankan bash review.sh 123 dan shell mengganti "$1" dengan 123, jadi skrip mengambil diff untuk PR 123. Claude Code mencetak tinjauan sebagai JSON, dengan teks di bidang result. Lihat flag system prompt untuk opsi lebih lanjut termasuk --system-prompt untuk sepenuhnya mengganti prompt default. Jika Anda menggantinya, jalankan juga dimulai tanpa snapshot status git.

Lanjutkan percakapan

Gunakan --continue untuk melanjutkan percakapan terbaru, atau --resume dengan ID sesi untuk melanjutkan percakapan tertentu. Pada Claude Code v2.1.257 atau lebih baru, ketika Anda memberikan --continue, Claude Code membuka sesi latar belakang yang telah selesai, tetapi bukan yang masih berjalan. Contoh ini menjalankan tinjauan, kemudian mengirim prompt tindak lanjut:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Jika Anda menjalankan beberapa percakapan, tangkap ID sesi untuk melanjutkan percakapan tertentu:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Anda dapat menjalankan dua perintah dari direktori yang berbeda: Claude Code menemukan sesi berdasarkan ID-nya di proyek apa pun di mesin ini. Sebagai ganti ID sesi, Anda dapat memberikan --resume jalur absolut ke file transkrip .jsonl sesi, dan Claude Code melanjutkan percakapan yang disimpan dalam file itu.

Langkah berikutnya

Agent SDK quickstart: bangun agen pertama Anda dengan Python atau TypeScript
CLI reference: semua bendera dan opsi CLI
GitHub Actions: gunakan Agent SDK dalam alur kerja GitHub
GitLab CI/CD: gunakan Agent SDK dalam pipeline GitLab

Agent dan pekerjaan paralel

MCP

Skills

Artifact

Otomatisasi

Panduan

Pemecahan masalah

Jalankan Claude Code secara programatis

Penggunaan dasar

Mulai lebih cepat dengan bare mode

Tugas latar belakang saat keluar

Hentikan jalankan dengan SIGTERM

Jika direktori kerja dihapus

Contoh

Saluran data melalui Claude

Tambahkan Claude ke skrip build

Dapatkan output terstruktur

Stream respons

Ikuti pesan subagent

Tangani retry API

Baca metadata sesi

Gagalkan CI ketika plugin atau server MCP tidak dimuat

Lacak pemasangan plugin

Persetujuan otomatis tool

Matikan permintaan izin dalam jalankan tanpa pengawasan

Buat commit

Sesuaikan system prompt

Lanjutkan percakapan

Langkah berikutnya

​Penggunaan dasar

​Mulai lebih cepat dengan bare mode

​Tugas latar belakang saat keluar

​Hentikan jalankan dengan SIGTERM

​Jika direktori kerja dihapus

​Contoh

​Saluran data melalui Claude

​Tambahkan Claude ke skrip build

​Dapatkan output terstruktur

​Stream respons

​Ikuti pesan subagent

​Tangani retry API

​Baca metadata sesi

​Gagalkan CI ketika plugin atau server MCP tidak dimuat

​Lacak pemasangan plugin

​Persetujuan otomatis tool

​Matikan permintaan izin dalam jalankan tanpa pengawasan

​Buat commit

​Sesuaikan system prompt

​Lanjutkan percakapan

​Langkah berikutnya

Penggunaan dasar

Mulai lebih cepat dengan bare mode

Tugas latar belakang saat keluar

Hentikan jalankan dengan SIGTERM

Jika direktori kerja dihapus

Contoh

Saluran data melalui Claude

Tambahkan Claude ke skrip build

Dapatkan output terstruktur

Stream respons

Ikuti pesan subagent

Tangani retry API

Baca metadata sesi

Gagalkan CI ketika plugin atau server MCP tidak dimuat

Lacak pemasangan plugin

Persetujuan otomatis tool

Matikan permintaan izin dalam jalankan tanpa pengawasan

Buat commit

Sesuaikan system prompt

Lanjutkan percakapan

Langkah berikutnya