Koordinasikan tim Claude Code sessions

Koordinasikan beberapa instance Claude Code yang bekerja bersama sebagai tim, dengan tugas bersama, pesan antar-agent, dan manajemen terpusat.

Tim agent memungkinkan Anda mengoordinasikan beberapa instance Claude Code yang bekerja bersama. Satu session bertindak sebagai team lead, mengoordinasikan pekerjaan, menugaskan tugas, dan mensintesis hasil. Rekan tim bekerja secara independen, masing-masing dalam context window-nya sendiri, dan berkomunikasi langsung satu sama lain. Anda juga dapat berbicara dengan rekan tim mana pun secara langsung tanpa melalui lead.

Sebelum Anda menyiapkan tim, periksa apakah opsi yang lebih ringan dapat menyelesaikan pekerjaan. Subagents bekerja dalam satu session, dan dengan cross-session messaging Claude dapat meneruskan temuan antar session yang Anda jalankan sendiri.

Kapan menggunakan tim agent

Tim agent paling efektif untuk tugas di mana eksplorasi paralel menambah nilai nyata. Lihat contoh use case untuk skenario lengkap. Use case terkuat adalah:

• Penelitian dan review: beberapa rekan tim dapat menyelidiki aspek berbeda dari masalah secara bersamaan, kemudian berbagi dan menantang temuan satu sama lain
• Modul atau fitur baru: rekan tim dapat masing-masing memiliki bagian terpisah tanpa saling mengganggu
• Debugging dengan hipotesis bersaing: rekan tim menguji teori berbeda secara paralel dan berkumpul pada jawaban lebih cepat
• Koordinasi lintas-layer: perubahan yang mencakup frontend, backend, dan tests, masing-masing dimiliki oleh rekan tim berbeda

Tim agent menambah overhead koordinasi dan menggunakan token secara signifikan lebih banyak daripada satu session. Mereka bekerja paling baik ketika rekan tim dapat beroperasi secara independen. Untuk tugas sekuensial, edit file yang sama, atau pekerjaan dengan banyak dependensi, satu session atau subagents lebih efektif.

Bandingkan dengan subagents

Baik tim agent maupun subagents memungkinkan Anda memparalelkan pekerjaan, tetapi mereka beroperasi berbeda. Untuk session terpisah yang melewatkan pesan satu sama lain tanpa tim, lihat cross-session messaging.

Gunakan subagents ketika Anda membutuhkan pekerja cepat dan terfokus yang melaporkan kembali. Gunakan tim agent ketika rekan tim perlu berbagi temuan, menantang satu sama lain, dan berkoordinasi sendiri.

Aktifkan tim agent

Tim agent dinonaktifkan secara default. Aktifkan dengan mengatur variabel environment CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ke 1, baik di environment shell Anda atau melalui settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Mengaktifkan tim agent juga mengubah delegasi biasa. Claude dapat memberi nama subagent dengan sendirinya, dan sementara tim agent diaktifkan, subagent yang diberi nama Claude diluncurkan sebagai rekan tim, sehingga tim dapat terbentuk bahkan ketika Anda tidak memintanya. Untuk informasi lebih lanjut, lihat Bagaimana Claude memulai tim agent; untuk mematikan perilaku ini, lihat Claude menspawn rekan tim alih-alih subagent.

Menspawn rekan tim juga memerlukan sesi interaktif. Dalam mode non-interaktif dengan flag -p, termasuk sesi Agent SDK, Claude tidak menspawn rekan tim, dan subagent yang diberi nama Claude berjalan sebagai subagent biasa bahkan dengan tim agent diaktifkan.

Mulai tim agent pertama Anda

Setelah mengaktifkan tim agent, jelaskan tugas dan rekan tim yang Anda inginkan dalam bahasa alami. Claude menelurkan mereka dan mengoordinasikan pekerjaan berdasarkan prompt Anda.

Contoh ini bekerja dengan baik karena tiga peran independen dan dapat mengeksplorasi masalah tanpa menunggu satu sama lain:

Saya merancang alat CLI yang membantu developer melacak komentar TODO di seluruh
codebase mereka. Buat tiga rekan tim untuk mengeksplorasi ini dari sudut berbeda:
satu pada UX, satu pada arsitektur teknis, satu memainkan devil's advocate.

Dari sana, Claude mengisi daftar tugas bersama dalam sesi yang memiliki Task tools, menelurkan rekan tim untuk setiap perspektif, membuat mereka mengeksplorasi masalah, dan mensintesis temuan ketika selesai.

Claude kadang-kadang dapat menggunakan subagents sebagai gantinya membuat tim. Subagents muncul di panel agent yang sama dengan rekan tim, jadi panel saja tidak mengkonfirmasi tim terbentuk. Jika Claude menelurkan subagents sebagai gantinya, tanyakan lagi dan secara eksplisit minta tim agent.

Panel lead mencantumkan rekan tim di panel agent di bawah input prompt. Dari panel:

• Panah atas dan bawah: pilih rekan tim
• Enter: buka transkrip rekan tim yang dipilih dan kirim pesan langsung kepadanya
• Escape: hapus pilihan. Saat Anda melihat transkrip rekan tim, Escape menghentikan giliran saat ini rekan tim tersebut

Mulai dari v2.1.199, baris rekan tim yang idle tetap berada di panel sementara rekan tim atau subagent mana pun masih bekerja, sehingga Anda dapat memilihnya untuk meninjau transkrip atau memberikan pekerjaan lebih lanjut. Setelah setiap agent di panel idle, baris idle bersembunyi setelah 30 detik dan muncul kembali pada giliran berikutnya rekan tim; rekan tim tetap berjalan dan dapat dialamatkan saat tersembunyi. Di v2.1.181 hingga v2.1.198, baris idle bersembunyi 30 detik setelah giliran sendirinya berakhir, bahkan sementara rekan tim lain masih bekerja; baris idle tidak disembunyikan di versi sebelum v2.1.181.

Ketika lebih dari tiga rekan tim idle sekaligus, baris di luar tiga pertama runtuh menjadi satu baris yang menghitung rekan tim yang runtuh, seperti 2 idle agents ketika lima idle. Pilih dan tekan Enter untuk memperluas baris yang runtuh, atau tekan Esc untuk meruntuhkannya lagi. Rekan tim yang bekerja, rekan tim yang gagal, dan rekan tim yang Anda lihat selalu mempertahankan baris mereka sendiri.

Jika Anda ingin setiap rekan tim di split pane-nya sendiri, lihat Pilih mode tampilan.

Kontrol tim agent Anda

Beri tahu lead apa yang Anda inginkan dalam bahasa alami. Ini menangani koordinasi tim, penugasan tugas, dan delegasi berdasarkan instruksi Anda.

Pilih mode tampilan

Tim agent mendukung dua mode tampilan:

• In-process: semua rekan tim berjalan di dalam terminal utama Anda. Gunakan tombol panah atas dan bawah di panel agent untuk memilih rekan tim, kemudian tekan Enter untuk melihatnya dan ketik untuk mengirim pesan kepadanya secara langsung. Bekerja di terminal apa pun, tidak ada setup tambahan yang diperlukan.
• Split panes: setiap rekan tim mendapat pane-nya sendiri. Anda dapat melihat output semua orang sekaligus dan klik ke dalam pane untuk berinteraksi secara langsung. Memerlukan tmux, atau iTerm2.

Default adalah "in-process". Atur "auto" untuk mengaktifkan split panes ketika Anda sudah berjalan di dalam session tmux, atau ketika terminal Anda adalah iTerm2 dengan CLI it2 yang terinstal, jatuh kembali ke in-process sebaliknya. Pengaturan "tmux" mengaktifkan mode split-pane dan auto-detects apakah akan menggunakan tmux atau iTerm2 berdasarkan terminal Anda.

Mulai dari v2.1.186, atur "iterm2" untuk menggunakan iTerm2 native split panes secara eksplisit. Mode ini memerlukan it2 CLI dan menampilkan error dengan perintah install jika it2 hilang. Prompt setup yang menawarkan untuk menginstal it2 atau beralih ke tmux muncul di bawah "auto" atau "tmux" ketika terminal Anda adalah iTerm2 dan tmux tersedia sebagai fallback.

Untuk mengganti default, atur teammateMode di ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Untuk menetapkan mode untuk satu session, teruskan sebagai flag:

claude --teammate-mode auto

Flag --teammate-mode bersifat eksperimental dan tidak muncul di claude --help.

Mode split-pane memerlukan baik tmux atau iTerm2 dengan it2 CLI. Untuk menginstal secara manual:

• tmux: instal melalui package manager sistem Anda. Lihat tmux wiki untuk instruksi spesifik platform.
• iTerm2: instal it2 CLI, kemudian aktifkan Python API di iTerm2 → Settings → General → Magic → Enable Python API.

Tentukan rekan tim dan model

Claude memutuskan jumlah rekan tim untuk dihasilkan berdasarkan tugas Anda, atau Anda dapat menentukan dengan tepat apa yang Anda inginkan:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code memilih model setiap rekan tim dari yang pertama dari ini yang berlaku:

1. Model yang prompt spawn Anda beri nama untuk rekan tim itu.
2. Untuk rekan tim yang dihasilkan dari definisi subagent, model definisi, di mana inherit memilih model lead.
3. CLAUDE_CODE_SUBAGENT_MODEL, ketika diatur ke apa pun selain inherit.
4. Model saat ini lead.

Jika Anda menetapkan CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, dua sumber pertama tidak berlaku. Claude Code memilih model setiap rekan tim dari CLAUDE_CODE_SUBAGENT_MODEL ketika diatur ke apa pun selain inherit, dan dari model lead saat ini sebaliknya. Memerlukan Claude Code v2.1.257 atau lebih baru.

Sebelum v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL datang pertama dalam urutan ini.

Claude Code memeriksa model yang dipilihnya untuk rekan tim terhadap availableModels allowlist organisasi Anda. Ketika allowlist memblokir nilai, Claude Code mengganti model lain:

• Family alias seperti opus: Pada Anthropic API dan Claude Platform di AWS, Claude Code menjalankan rekan tim pada versi terbaru dari keluarga itu yang allowlist izinkan. Pada provider dengan ID model spesifik provider, di mana substitusi tidak beroperasi, alias yang diblokir jatuh kembali seperti nilai yang diblokir lainnya per bullet berikutnya
• Nilai yang diblokir lainnya, termasuk family alias pada provider di mana substitusi tidak beroperasi, atau yang keluarganya tidak memiliki versi yang diizinkan: Claude Code menjalankan rekan tim pada model lead sebagai gantinya. Jika Anda menetapkan CLAUDE_CODE_SUBAGENT_MODEL, Claude Code mencoba model itu terlebih dahulu, di bawah aturan yang sama ini

Rekan tim mewarisi effort level lead. Dalam mode split-pane ini berlaku dari v2.1.186; versi sebelumnya tidak meneruskan effort session lead ke rekan tim split-pane.

Perlukan rekan tim merencanakan sebelum mengimplementasikan

Untuk tugas kompleks atau berisiko, Anda dapat memerlukan rekan tim untuk merencanakan sebelum mengimplementasikan. Rekan tim yang Claude hasilkan saat lead berada dalam plan mode bekerja dalam mode rencana read-only sampai rencananya siap. Alihkan lead ke plan mode terlebih dahulu, kemudian minta rekan tim:

Spawn an architect teammate to refactor the authentication module.

Ketika rekan tim selesai merencanakan, mereka mengirim permintaan persetujuan rencana ke lead. Claude Code menyetujui rencana dalam session lead segera setelah permintaan tiba, tanpa lead meninjau. Edit dan perintah rekan tim masih melalui prompt izin yang dijelaskan dalam Permissions. Setelah disetujui, rekan tim keluar dari plan mode dan mulai implementasi.

Berbicara dengan rekan tim secara langsung

Setiap rekan tim adalah session Claude Code penuh dan independen. Anda dapat mengirim pesan ke rekan tim mana pun secara langsung untuk memberikan instruksi tambahan, mengajukan pertanyaan lanjutan, atau mengalihkan pendekatan mereka.

• Mode in-process: gunakan tombol panah atas dan bawah di panel agent untuk memilih rekan tim, kemudian tekan Enter untuk melihat sessionnya dan ketik untuk mengirim pesan kepadanya. Tekan x pada rekan tim yang dipilih untuk menghentikannya. Tekan Ctrl+T untuk toggle daftar tugas.
• Mode split-pane: klik ke dalam pane rekan tim untuk berinteraksi dengan session mereka secara langsung. Setiap rekan tim memiliki tampilan penuh dari terminal mereka sendiri.

Saat Anda melihat rekan tim in-process, teks biasa dan skills pergi ke rekan tim itu, tetapi perintah built-in masih berjalan dalam session lead.

Model rekan tim dan fast mode diperbaiki ketika mereka spawn, jadi /model dan /fast hanya mengubah pengaturan lead. Mulai dari v2.1.199, mengetik salah satu perintah saat melihat rekan tim menampilkan pemberitahuan bahwa perubahan berlaku untuk lead; versi sebelumnya menerapkannya ke lead tanpa indikasi. /effort masih berlaku untuk giliran rekan tim yang lebih baru, karena rekan tim mengikuti effort level lead.

Tetapkan dan klaim tugas

Daftar tugas bersama mengoordinasikan pekerjaan di seluruh tim. Lead membuat tugas dan rekan tim mengerjakannya. Tugas memiliki tiga status: pending, in progress, dan completed. Tugas juga dapat bergantung pada tugas lain: tugas pending dengan dependensi yang tidak terselesaikan tidak dapat diklaim sampai dependensi tersebut selesai.

Agent tanpa Task tools mengoordinasikan melalui pesan sebagai gantinya dari daftar tugas bersama.

Lead dapat menugaskan tugas secara eksplisit, atau rekan tim dapat self-claim:

• Lead menugaskan: beri tahu lead tugas mana yang diberikan kepada rekan tim mana
• Self-claim: setelah menyelesaikan tugas, rekan tim mengambil tugas unassigned, unblocked berikutnya sendiri

Klaim tugas menggunakan file locking untuk mencegah race conditions ketika beberapa rekan tim mencoba mengklaim tugas yang sama secara bersamaan.

Matikan rekan tim

Untuk mengakhiri session rekan tim dengan baik, rujuk dengan nama. Misalnya, dengan rekan tim bernama researcher:

Ask the researcher teammate to shut down

Lead mengirim permintaan shutdown. Rekan tim dapat menyetujui, keluar dengan baik, atau menolak dengan penjelasan.

Direktori bersama tim dibersihkan secara otomatis ketika session berakhir, jadi tidak ada langkah pembersihan terpisah. Lihat Architecture untuk direktori mana yang dihapus dan mana yang bertahan untuk session yang dilanjutkan.

Terapkan quality gates dengan hooks

Gunakan hooks untuk menerapkan aturan ketika rekan tim menyelesaikan pekerjaan atau tugas dibuat atau diselesaikan:

• TeammateIdle: berjalan ketika rekan tim akan idle. Keluar dengan kode 2 untuk mengirim umpan balik dan membuat rekan tim tetap bekerja.
• TaskCreated: berjalan ketika tugas sedang dibuat. Keluar dengan kode 2 untuk mencegah pembuatan dan mengirim umpan balik.
• TaskCompleted: berjalan ketika tugas ditandai selesai. Keluar dengan kode 2 untuk mencegah penyelesaian dan mengirim umpan balik.

Bagaimana tim agent bekerja

Bagian ini mencakup arsitektur dan mekanik di balik tim agent. Jika Anda ingin mulai menggunakannya, lihat Kontrol tim agent Anda di atas.

Bagaimana Claude memulai tim agent

Untuk memulai tim, minta Claude untuk rekan tim. Claude meluncurkan rekan tim ketika memanggil Agent tool dengan name sementara tim agent diaktifkan, kecuali panggilan adalah fork atau melewatkan isolation pada panggilan itu sendiri. Claude Code tidak meminta Anda untuk mengonfirmasi peluncuran.

Claude juga memberi nama subagent biasa dengan sendirinya sehingga dapat mengirim pesan kepada mereka nanti. Panggilan-panggilan tersebut mengikuti aturan yang sama, jadi tim dapat terbentuk bahkan ketika Anda tidak memintanya. Jika Anda menginginkan subagent sebagai gantinya, matikan tim agent.

Arsitektur

Tim agent terdiri dari:

Mailbox setiap agent adalah file JSON di ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code memvalidasi setiap entri ketika membaca file mailbox. Entri yang tidak sesuai dengan format pesan dilaporkan sebagai kesalahan dan dihapus dari file; pesan yang valid masih dikirimkan. Sebelum v2.1.207, satu entri mailbox yang salah format menyebabkan kesalahan berulang setiap detik dan memblokir pengiriman untuk mailbox itu sampai Anda menghapus file secara manual.

Claude Code melaporkan pesan sebagai terkirim hanya ketika penulisan ke file mailbox penerima berhasil, baik pesan itu teks biasa atau pesan protokol terstruktur seperti persetujuan rencana atau permintaan shutdown. Ketika penulisan gagal, misalnya karena disk penuh atau direktori mailbox tidak dapat ditulis, agent pengirim menerima kesalahan dan tidak ada yang dikirim. Lihat Gagal menulis ke inbox rekan tim untuk pesan kesalahan dan langkah pemulihan.

Claude Code mengelola dependensi tugas secara otomatis: ketika rekan tim menyelesaikan tugas yang tugas lain bergantung padanya, tugas yang diblokir membuka tanpa tindakan apa pun dari Anda.

Tim dan tugas disimpan secara lokal dengan nama yang diturunkan dari sesi. Nama adalah session- diikuti oleh delapan karakter pertama dari session ID:

• Konfigurasi tim: ~/.claude/teams/{team-name}/config.json
• Daftar tugas: ~/.claude/tasks/{team-name}/

Claude Code menghasilkan keduanya secara otomatis saat startup sesi dan memperbarui mereka saat rekan tim bergabung, idle, atau pergi. Direktori konfigurasi tim dihapus ketika sesi berakhir. Direktori daftar tugas tetap ada secara lokal dan tidak pernah diunggah, jadi sesi yang dilanjutkan menyimpan tugas mereka. Retensi diatur oleh cleanupPeriodDays yang sama yang sudah Anda kontrol untuk transkrip sesi, mengikuti aturan pembersihan retensi.

Konfigurasi tim menyimpan status runtime seperti session IDs dan tmux pane IDs, jadi jangan mengeditnya dengan tangan atau pre-author: perubahan Anda ditimpa pada update status berikutnya.

Untuk mendefinisikan peran rekan tim yang dapat digunakan kembali, gunakan subagent definitions sebagai gantinya.

Konfigurasi tim berisi array members dengan nama setiap anggota dan agent ID. Entri lead selalu membawa tipe agent team-lead. Entri rekan tim membawa tipe agent apa pun yang lead beri nama saat menghasilkannya, baik tipe built-in atau subagent definition, dan menghilangkan field ketika lead tidak memberi nama apa pun. Rekan tim dapat membaca file ini untuk menemukan anggota tim lainnya.

Tidak ada padanan tingkat proyek dari konfigurasi tim. File seperti .claude/teams/teams.json di direktori proyek Anda tidak dikenali sebagai konfigurasi; Claude memperlakukannya sebagai file biasa.

Gunakan subagent definitions untuk rekan tim

Ketika menghasilkan rekan tim dalam mode tampilan apa pun, Anda dapat mereferensikan tipe subagent dari proyek, pengguna, atau subagent scope yang dikelola. Ini memungkinkan Anda mendefinisikan peran sekali, seperti security-reviewer atau test-runner, dan menggunakannya kembali baik sebagai subagent yang didelegasikan maupun sebagai rekan tim agent team.

Untuk menggunakan subagent definition, sebutkan berdasarkan nama ketika meminta Claude untuk menghasilkan rekan tim:

Hasilkan rekan tim menggunakan tipe agent security-reviewer untuk mengaudit modul auth.

Claude Code membaca subagent definition yang Anda beri nama dan menerapkan bagian-bagian ini ke rekan tim. Jika bagian bergantung pada mode tampilan rekan tim, entri mengatakan demikian:

• tools: Claude Code membatasi rekan tim ke tools dalam daftar tools definition. Untuk rekan tim in-process, Claude Code menambahkan SendMessage ke daftar itu, dan dalam sesi yang memiliki Task tools menambahkan TaskCreate, TaskGet, TaskList, dan TaskUpdate juga.
• model: Claude Code menggunakan model definition dalam mode tampilan apa pun ketika spawn prompt Anda tidak memberi nama satu. Lihat bagaimana Claude Code memilih model rekan tim.
• Body: untuk rekan tim in-process, Claude Code menambahkan body definition ke system prompt default-nya sebagai instruksi tambahan. Untuk rekan tim split-pane, Claude Code menggunakan body sebagai pengganti system prompt default-nya.
• skills: Claude Code tidak menerapkan skills definition ke rekan tim dalam mode tampilan apa pun. Rekan tim memuat skills dari pengaturan proyek dan pengguna Anda.
• mcpServers: untuk rekan tim split-pane, Claude Code menerapkan mcpServers definition di bawah aturan untuk field itu, yang mencakup sesi yang dimulai dengan --agent juga. Rekan tim in-process mengabaikan field dan memuat MCP servers dari pengaturan proyek dan pengguna Anda.

Ketika Claude mengirim pesan ke rekan tim in-process yang tidak lagi berjalan, Claude Code membawanya kembali dalam sesi yang sama, memulihkan percakapan apa pun yang disimpan untuk itu, dan memberikan pesan sebagai prompt berikutnya. Setelah Anda melanjutkan sesi, rekan tim tidak dibawa kembali dengan cara ini, sesuai batasan resume.

Untuk rekan tim yang dibawanya kembali, Claude Code menerapkan kembali definition yang berasal dari direktori .claude/agents/ proyek atau direktori --add-dir hanya jika Anda telah mempercayai folder tempat file agent berada. Mempercayai folder induk tidak dihitung. Sampai saat itu, rekan tim kembali tanpa tools atau instruksi definition apa pun, hanya menyimpan tools yang Claude Code tambahkan ke setiap rekan tim in-process. Lihat definisi agent rekan tim tidak dipulihkan untuk teks pemberitahuan.

Izin

Rekan tim dimulai dengan mode izin lead, kecuali mode dontAsk, yang tidak mereka warisi. Jika lead berjalan dengan --dangerously-skip-permissions, semua rekan tim juga demikian. Setelah dihasilkan, Anda dapat mengubah mode izin rekan tim individual, tetapi Anda tidak dapat mengatur mode izin per-rekan tim pada waktu spawn.

Prompt izin rekan tim muncul di sesi lead, jadi setujui mereka di sana sendiri. Persetujuan rencana adalah pengecualian yang dirancang: sesi lead memberikan persetujuan rencana rekan tim tanpa prompt terpisah kepada Anda.

Pesan antar agent

Ketika satu agent mengirim agent lain pesan melalui SendMessage, Claude Code memberi tahu agent penerima bahwa pesan itu berasal dari sesi Claude lain, bukan dari Anda. Rekan tim tidak dapat menyetujui prompt izin atau memberikan persetujuan atas nama Anda, dan rekan tim yang ditolak tindakannya tidak dapat menyampaikannya ke rekan tim lain untuk melewati pemeriksaan. Aturan yang sama berlaku untuk pesan yang tiba dari salah satu sesi Claude Code lain Anda, di luar tim sepenuhnya.

Dalam auto mode, classifier menerapkan dua pemeriksaan ke pesan antar agent:

• Ini memperlakukan klaim persetujuan yang disalurkan dari agent lain sebagai input yang tidak dipercaya daripada konfirmasi dari Anda.
• Ini meninjau setiap pesan sebelum Claude Code mengirimkannya, baik pesan biasa atau pesan protokol terstruktur seperti permintaan shutdown atau respons persetujuan rencana. Pesan yang diblokir tidak pernah mencapai penerima.

Context dan komunikasi

Setiap rekan tim memiliki context window-nya sendiri. Ketika dihasilkan, rekan tim memuat konteks proyek yang sama seperti session reguler: CLAUDE.md, MCP servers, dan skills. Mereka juga menerima spawn prompt dari lead. Riwayat percakapan lead tidak terbawa.

Bagaimana rekan tim berbagi informasi:

• Pengiriman pesan otomatis: ketika rekan tim mengirim pesan, mereka dikirimkan secara otomatis ke penerima. Lead tidak perlu polling untuk update.
• Notifikasi idle: ketika rekan tim selesai dan berhenti, mereka secara otomatis memberi tahu lead dan menyertakan jawaban akhir mereka dalam notifikasi. Rekan tim yang giliran berakhir pada kesalahan API memberi tahu lead bahwa itu gagal dan menyertakan teks kesalahan.
• Daftar tugas bersama: agent yang memiliki Task tools dapat melihat status tugas dan mengklaim pekerjaan yang tersedia.
• Pesan rekan tim: kirim pesan ke satu rekan tim spesifik berdasarkan nama. Untuk menjangkau semua orang, kirim satu pesan per penerima.

Lead menugaskan setiap rekan tim nama ketika menghasilkannya, dan rekan tim mana pun dapat mengirim pesan ke yang lain berdasarkan nama itu. Untuk mendapatkan nama yang dapat diprediksi yang dapat Anda referensikan dalam prompt kemudian, beri tahu lead apa yang harus dipanggil setiap rekan tim dalam instruksi spawn Anda.

Penggunaan token

Tim agent menggunakan token secara signifikan lebih banyak daripada satu session. Setiap rekan tim memiliki context window-nya sendiri, dan penggunaan token skala dengan jumlah rekan tim aktif. Untuk penelitian, review, dan pekerjaan fitur baru, token tambahan biasanya berharga. Untuk tugas rutin, satu session lebih cost-effective. Lihat biaya token tim agent untuk panduan penggunaan.

Permintaan rekan tim in-process jatuh di luar cache TTL bucket percakapan utama, jadi cache-nya berlaku selama lima menit secara default, termasuk pada langganan Claude. Untuk menyimpannya selama satu jam, atur subagentPromptCacheTtl ke 1h. API menagih penulisan cache 1 jam dengan tarif yang lebih tinggi.

Contoh use case

Contoh-contoh ini menunjukkan bagaimana tim agent menangani tugas di mana eksplorasi paralel menambah nilai.

Jalankan code review paralel

Seorang reviewer tunggal cenderung tertarik pada satu jenis masalah pada satu waktu. Membagi kriteria review menjadi domain independen berarti keamanan, kinerja, dan test coverage semuanya mendapat perhatian menyeluruh secara bersamaan. Prompt menugaskan setiap rekan tim lensa yang berbeda sehingga mereka tidak tumpang tindih:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Setiap reviewer bekerja dari PR yang sama tetapi menerapkan filter berbeda. Lead mensintesis temuan di ketiga setelah mereka selesai.

Investigasi dengan hipotesis bersaing

Ketika akar penyebab tidak jelas, satu agent cenderung menemukan satu penjelasan yang masuk akal dan berhenti mencari. Prompt melawan ini dengan membuat rekan tim secara eksplisit adversarial: pekerjaan setiap orang bukan hanya menyelidiki teori mereka sendiri tetapi menantang yang lain.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

Struktur debat adalah mekanisme kunci di sini. Investigasi sekuensial menderita dari anchoring: setelah satu teori dieksplorasi, investigasi berikutnya bias terhadapnya.

Dengan beberapa investigator independen secara aktif mencoba membantah satu sama lain, teori yang bertahan jauh lebih mungkin menjadi akar penyebab sebenarnya.

Best practices

Berikan rekan tim konteks yang cukup

Rekan tim memuat konteks proyek secara otomatis, termasuk CLAUDE.md, MCP servers, dan skills, tetapi mereka tidak mewarisi riwayat percakapan lead. Lihat Context dan komunikasi untuk detail. Sertakan detail spesifik tugas dalam spawn prompt:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Pilih ukuran tim yang sesuai

Tidak ada batas keras pada jumlah rekan tim, tetapi batasan praktis berlaku:

• Biaya token skala linear: setiap rekan tim memiliki context window-nya sendiri dan mengkonsumsi token secara independen. Lihat biaya token tim agent untuk detail.
• Overhead koordinasi meningkat: lebih banyak rekan tim berarti lebih banyak komunikasi, koordinasi tugas, dan potensi konflik
• Diminishing returns: di luar titik tertentu, rekan tim tambahan tidak mempercepat pekerjaan secara proporsional

Mulai dengan 3-5 rekan tim untuk sebagian besar workflow. Ini menyeimbangkan pekerjaan paralel dengan koordinasi yang dapat dikelola. Jika Anda memiliki 15 tugas independen, 3 rekan tim adalah titik awal yang baik.

Skala naik hanya ketika pekerjaan benar-benar menguntungkan dari rekan tim bekerja secara bersamaan. Tiga rekan tim terfokus sering mengungguli lima yang tersebar.

Ukuran tugas dengan tepat

• Terlalu kecil: overhead koordinasi melebihi manfaat
• Terlalu besar: rekan tim bekerja terlalu lama tanpa check-in, meningkatkan risiko usaha yang terbuang
• Tepat: unit self-contained yang menghasilkan deliverable yang jelas, seperti fungsi, file test, atau review

Tunggu rekan tim selesai

Kadang-kadang lead mulai mengimplementasikan tugas sendiri alih-alih menunggu rekan tim. Jika Anda memperhatikan ini:

Tunggu rekan tim Anda menyelesaikan tugas mereka sebelum melanjutkan

Mulai dengan penelitian dan review

Jika Anda baru mengenal tim agent, mulai dengan tugas yang memiliki batas yang jelas dan tidak memerlukan penulisan kode: review PR, penelitian library, atau investigasi bug. Tugas-tugas ini menunjukkan nilai eksplorasi paralel tanpa tantangan koordinasi yang datang dengan implementasi paralel.

Hindari konflik file

Dua rekan tim mengedit file yang sama menyebabkan overwrites. Pecah pekerjaan sehingga setiap rekan tim memiliki set file berbeda.

Monitor dan kemudi

Periksa kemajuan rekan tim, alihkan pendekatan yang tidak berfungsi, dan sintesis temuan saat tiba. Membiarkan tim berjalan tanpa diawasi terlalu lama meningkatkan risiko usaha yang terbuang.

Troubleshooting

Rekan tim tidak muncul

Jika rekan tim tidak muncul setelah Anda meminta Claude untuk membuat mereka:

• Dalam mode in-process, rekan tim muncul di panel agen di bawah input prompt. Gunakan tombol panah atas dan bawah untuk memilih satu, kemudian tekan Enter untuk melihatnya.
• Baris rekan tim yang hilang setelah diam telah disembunyikan, bukan dihentikan. Baris idle menyembunyikan 30 detik setelah seluruh panel menjadi idle dan muncul kembali pada giliran rekan tim berikutnya. Ketika lebih dari tiga rekan tim idle, baris surplus mereka runtuh menjadi satu baris N idle agents yang Enter perluas. Kirim pesan ke rekan tim berdasarkan nama untuk membawa baris yang disembunyikan kembali.
• Periksa bahwa tugas yang Anda berikan Claude cukup kompleks untuk menjamin rekan tim. Claude memutuskan apakah akan menelurkan mereka berdasarkan tugas.
• Jika Anda secara eksplisit meminta split panes, pastikan tmux diinstal dan tersedia di PATH Anda:

  which tmux
  

• Untuk iTerm2, verifikasi it2 CLI diinstal dan Python API diaktifkan di preferensi iTerm2.

Claude menelurkan rekan tim alih-alih subagents

Sementara agent teams diaktifkan, subagent yang Claude namai dalam sesi lead diluncurkan sebagai rekan tim. Claude dapat mengganti nama subagents sendiri, jadi ini dapat terjadi selama delegasi yang tidak pernah Anda bingkai sebagai pekerjaan tim.

Untuk membuat subagents bernama diluncurkan sebagai subagents lagi, matikan agent teams dengan mengatur CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ke 0:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Anda tidak perlu memulai sesi baru: Claude Code menerapkan kembali nilai env file pengaturan ke sesi yang berjalan ketika Anda menyimpan, dan membaca ulang variabel setiap kali Claude menelurkan subagent, jadi subagent berikutnya yang Claude namai diluncurkan sebagai subagent.

Mengatur variabel ke 0 di settings.json pengguna Anda mengganti shell export. Sumber pengaturan lainnya masih dapat mengaktifkan agent teams:

• File pengaturan dengan prioritas lebih tinggi: pengaturan proyek, pengaturan lokal, dan payload --settings diterapkan setelah pengaturan pengguna, jadi entri env yang mengatur variabel ke 1 di salah satu dari mereka menang. Lihat Settings precedence.
• Managed settings: managed settings diterapkan setelah setiap sumber lainnya. Jika organisasi Anda mengaktifkan agent teams di sana, minta administrator Anda untuk mengubah nilai yang dikelola.

Setelah perubahan, Claude mungkin masih mengganti nama subagents, dan nama terus bekerja sebagai alamat SendMessage. Claude menerima hasil setiap subagent ketika selesai.

Terlalu banyak permission prompts

Permintaan izin rekan tim naik ke lead, yang dapat menciptakan gesekan. Pre-approve operasi umum di pengaturan izin Anda sebelum menelurkan rekan tim untuk mengurangi gangguan.

Agents berhenti lebih awal

Rekan tim dapat berhenti setelah mengalami errors alih-alih pulih. Periksa output mereka dengan memilih rekan tim di panel agen dan menekan Enter dalam mode in-process, atau dengan mengklik pane dalam mode split, kemudian baik:

• Berikan instruksi tambahan kepada mereka secara langsung
• Hasilkan rekan tim pengganti untuk melanjutkan pekerjaan

Pesan dari lead atau rekan tim lain membangunkan rekan tim in-process yang menunggu untuk mencoba ulang permintaan API yang gagal, sehingga mencoba ulang segera alih-alih menunggu penundaan percobaan ulang penuh.

Lead dapat berhenti lebih awal juga, memutuskan tim selesai sebelum semua tugas benar-benar selesai. Jika itu terjadi, beri tahu untuk terus.

Orphaned tmux sessions

Jika session tmux bertahan setelah sesi Claude Code berakhir, mungkin tidak sepenuhnya dibersihkan. Daftar session dan bunuh yang dibuat oleh tim:

tmux ls
tmux kill-session -t <session-name>

Keterbatasan

Tim agent bersifat eksperimental. Keterbatasan saat ini untuk diketahui:

• Tidak ada session resumption dengan rekan tim in-process: /resume dan /rewind tidak mengembalikan rekan tim in-process. Setelah melanjutkan session, lead dapat mencoba mengirim pesan ke rekan tim yang tidak lagi ada. Jika ini terjadi, beri tahu lead untuk menelurkan rekan tim baru.
• Status tugas dapat tertinggal: rekan tim kadang-kadang gagal menandai tugas sebagai selesai, yang memblokir tugas dependen. Jika tugas tampak terjebak, periksa apakah pekerjaan benar-benar selesai dan perbarui status tugas secara manual atau beri tahu lead untuk mendorong rekan tim.
• Shutdown dapat lambat: rekan tim menyelesaikan permintaan atau tool call saat ini sebelum shutdown, yang dapat memakan waktu.
• Satu tim per session: sebuah session memiliki tepat satu tim, yang dibatasi pada session tersebut. Anda tidak dapat membuat tim bernama tambahan atau berbagi tim di seluruh session.
• Tidak ada tim bersarang: rekan tim tidak dapat menelurkan rekan tim mereka sendiri. Hanya lead yang dapat mengelola tim.
• Tidak ada background subagents dari rekan tim in-process: subagents rekan tim in-process sendiri berjalan di foreground, karena pekerjaan background rekan tim tidak dapat bertahan lebih lama dari proses lead. Claude Code mengembalikan error ketika rekan tim menelurkan subagent yang definisinya menetapkan background: true. Permintaan run_in_background: true rekan tim juga gagal, baik dengan error atau dengan berjalan diam-diam di foreground, seperti yang dijelaskan dalam bagaimana Claude Code memilih foreground atau background. Subagents yang diluncurkan dari percakapan utama mengikuti default background.
• Lead tetap: session utama adalah lead seumur hidupnya. Anda tidak dapat mempromosikan rekan tim ke lead atau mentransfer kepemimpinan.
• Izin ditetapkan pada spawn: rekan tim dimulai dengan mode izin yang dijelaskan di bawah Izin. Anda dapat mengubah mode izin rekan tim individual setelah menelurkan, tetapi Anda tidak dapat mengatur mode izin per-rekan tim pada waktu spawn.
• Split panes memerlukan tmux atau iTerm2: mode in-process default bekerja di terminal apa pun. Mode split-pane tidak didukung di integrated terminal VS Code, Windows Terminal, atau Ghostty.

Langkah berikutnya

Jelajahi pendekatan terkait untuk pekerjaan paralel dan delegasi:

• Delegasi ringan: subagents menelurkan agent pembantu untuk penelitian atau verifikasi dalam session Anda, lebih baik untuk tugas yang tidak memerlukan koordinasi inter-agent
• Pesan antar session Anda sendiri: cross-session messaging memungkinkan Claude melewatkan temuan antar session yang Anda jalankan sendiri
• Session paralel manual: Git worktrees memungkinkan Anda menjalankan beberapa session Claude Code sendiri tanpa koordinasi tim otomatis