Jawaban singkat untuk pertanyaan yang paling sering diajukan pembaca tentang topik ini.
Cara headless mode Claude Code menjalankan agen secara non-interaktif dengan claude -p, agar bisa dirangkai ke CI/CD, dibatasi tool-nya, dan dibaca keluarannya.
Matthews Wong
Software Engineer
Ringkasan Utama
Headless mode Claude Code menjalankan agen secara non-interaktif dengan perintah claude -p, mencetak hasil lalu keluar alih-alih membuka chat. Inilah cara merangkai Claude ke pipeline CI/CD, pre-commit hook, dan skrip: berikan sebuah prompt, batasi tool dan izinnya, baca keluaran JSON yang terstruktur, lalu bertindak berdasarkan exit code.
Kebanyakan orang mengenal Claude Code sebagai chat terminal interaktif: Anda mengetik, ia bekerja, Anda menyetujui. Loop itu bagus untuk coding eksploratif dan tak berguna untuk otomasi, karena sebuah CI runner tidak punya siapa pun untuk menjawab promptnya. Untuk menaruh agen di dalam pipeline, Anda butuh ia berjalan sekali, mengerjakan tugas, lalu menyingkir.
Headless mode adalah jalur non-interaktif itu. Anda memanggil Claude Code dengan sebuah prompt dan sekumpulan flag, ia berjalan sampai selesai tanpa percakapan, lalu melapor kembali dalam bentuk yang bisa diurai skrip. Panduan ini membahas perintah intinya, cara mengontrol apa yang boleh dilakukannya, dan cara menjalankannya dengan aman di CI tanpa membuka pintu lebar-lebar.
Headless mode, disebut juga print mode, adalah Claude Code yang dipanggil dengan flag -p dan sebuah prompt. Alih-alih memulai sesi interaktif, ia memproses prompt, memancarkan keluarannya ke standard out, lalu keluar dengan sebuah status code. Itu menjadikannya program baris perintah biasa yang bisa Anda pipe, redirect, dan panggil dari skrip atau job mana pun.
Beberapa sifat membuatnya cocok untuk otomasi ketimbang chat sehari-hari:
Pemanggilan paling sederhana memberikan sebuah string prompt setelah -p. Untuk otomasi Anda hampir selalu menambahkan format keluaran, karena mengurai teks bebas itu rapuh. Minta JSON dan Anda mendapatkan objek terstruktur berisi hasil dan metadata seperti penggunaan token yang bisa Anda catat atau jadikan asersi.
Sebuah pemanggilan CI minimal yang membatasi tool dan mengembalikan JSON terlihat seperti ini:
claude -p "Review the staged diff and fail if any TODO is left" \
--output-format json \
--allowedTools "Read,Grep,Glob" \
--permission-mode plan \
--max-turns 12Selalu pasang allowlist tool yang eksplisit di run headless. Dalam sebuah skrip tidak ada siapa pun untuk menyetujui tindakan berisiko, sehingga agen tanpa batasan akan mandek menunggu input atau, lebih buruk, bebas melakukan apa pun yang diarahkan promptnya. Menyebutkan tool persis yang boleh dipakainya mengubah run menjadi langkah yang dapat diprediksi dan terbatas.
Di dalam pipeline, headless Claude Code hanyalah satu langkah lagi yang entah berhasil atau gagal. Polanya sama di semua sistem CI: autentikasi, jalankan perintah dengan izin ketat, lalu bercabang berdasarkan hasilnya.
Agen non-interaktif persis seberbahaya izin yang Anda berikan kepadanya, karena tidak ada manusia dalam loop untuk menangkap langkah yang buruk. Seluruh model keamanan bertumpu pada mempersempit run ke minimum yang dibutuhkannya dan menjalankannya di tempat yang tidak bisa menimbulkan kerusakan permanen.
Dalam praktik itu berarti menggabungkan allowlist tool yang ketat dengan lingkungan yang terisolasi. Sebuah CI runner sudah bersifat sementara, yang membantu, tetapi sebuah job yang meng-clone repo Anda dan memegang API key sungguhan tetap layak di-sandbox, sehingga instruksi hasil prompt injection yang tersembunyi dalam kode yang dibacanya tidak bisa menjangkau lebih jauh dari runner.
Jangan pernah menjalankan headless mode dengan pemeriksaan izin sepenuhnya dilewati terhadap apa pun yang Anda pedulikan. Melewati persetujuan dalam lingkungan tanpa sandbox memberi satu prompt yang dimanipulasi jangkauan yang sama dengan kredensial dalam job itu. Jika Anda harus melewati prompt untuk otomasi, lakukan di dalam container atau virtual machine tanpa akses tetap ke produksi.
Begitu Claude Code menjadi sebuah perintah, job yang berguna adalah yang berulang, mudah dijelaskan, dan murah diverifikasi.
Headless mode adalah sambungan antara Claude Code dan sisa toolchain Anda. Gunakan claude -p setiap kali Anda ingin agen berjalan sekali lalu melapor kembali, pasang tool dan izinnya secara ketat, baca JSON alih-alih mengorek teks, dan jaga tiap run tanpa pengawasan tetap di dalam sandbox. Lakukan itu dan agen menjadi sekadar satu langkah andal lagi dalam pipeline.