Koordinasikan tim Claude Code sessions

Kapan menggunakan tim agent

• 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

Bandingkan dengan subagents

Aktifkan tim agent

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

Mulai tim agent pertama Anda

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.

• 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

Kontrol tim agent Anda

Pilih 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.

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• 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

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

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.

• 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

Perlukan rekan tim merencanakan sebelum mengimplementasikan

Spawn an architect teammate to refactor the authentication module.

Berbicara dengan rekan tim secara langsung

• 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.

• /compact, /clear, dan /rewind bertindak pada percakapan lead, sehingga Claude Code meminta Anda untuk mengonfirmasi sebelum menjalankan salah satunya dari tampilan ini.
• /model dan /fast menetapkan model dan fast mode lead, bukan milik rekan tim, sehingga keduanya tidak berjalan dari tampilan ini. Sebuah pemberitahuan memberi tahu Anda alasannya.

Tetapkan dan klaim tugas

• 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

Matikan rekan tim

Ask the researcher teammate to shut down

Terapkan quality gates dengan hooks

• 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.

Cara kerja tim agent

Cara Claude memulai tim agent

Arsitektur

• Konfigurasi tim: ~/.claude/teams/{team-name}/config.json. Claude Code menghapus direktori konfigurasi tim ketika sesi berakhir.
• Daftar tugas: ~/.claude/tasks/{team-name}/. Direktori ini tetap ada di disk setelah sesi berakhir. Untuk mengubah berapa lama Claude Code menyimpannya, atur cleanupPeriodDays.

Gunakan definisi subagent untuk rekan kerja

Spawn a teammate using the security-reviewer agent type to audit the auth module.

• tools: Claude Code membatasi rekan kerja ke tool dalam daftar tools definisi. Untuk rekan kerja dalam proses, Claude Code menambahkan SendMessage ke daftar itu, dan dalam sesi yang memiliki Task tools juga menambahkan TaskCreate, TaskGet, TaskList, dan TaskUpdate.
• model: Claude Code menggunakan model definisi di mode tampilan mana pun ketika prompt spawn Anda tidak menamai satu. Lihat bagaimana Claude Code memilih model rekan kerja.
• disallowedTools: untuk rekan kerja dalam proses, Claude Code menghapus tool dalam disallowedTools definisi dari kumpulan tool rekan kerja. SendMessage dan Task tools yang ditambahkannya tetap tersedia bahkan ketika daftar tersebut menamainya.
• effort: untuk rekan kerja dalam proses, Claude Code menerapkan effort definisi di bawah aturan effort frontmatter.
• autoCompactWindow: untuk rekan kerja dalam proses, Claude Code menerapkan autoCompactWindow definisi di bawah aturan bidang tersebut. Rekan kerja split-pane mengabaikan bidang ini. Memerlukan Claude Code v2.1.296 atau yang lebih baru.
• Body: untuk rekan kerja dalam proses, Claude Code menambahkan body definisi ke system prompt defaultnya sebagai instruksi tambahan. Untuk rekan kerja split-pane, Claude Code menggunakan body sebagai pengganti system prompt defaultnya.
• skills: Claude Code tidak menerapkan skills definisi ke rekan kerja di mode tampilan mana pun. Rekan kerja memuat skills dari pengaturan proyek dan pengguna Anda.
• mcpServers: untuk rekan kerja split-pane, Claude Code menerapkan mcpServers definisi di bawah aturan untuk bidang itu, yang mencakup sesi yang dimulai dengan --agent juga. Rekan kerja dalam proses mengabaikan bidang dan memuat server MCP dari pengaturan proyek dan pengguna Anda.

Izin

• --disallowedTools dan --tools: rekan kerja dimulai dengan aturan deny baris perintah dan daftar tool milik pemimpin. Memerlukan Claude Code v2.1.309 atau yang lebih baru.
• --allowedTools: Claude Code tidak meneruskan flag ini ke rekan kerja split-pane, sehingga tindakan yang Anda izinkan hanya dengan flag ini tidak disetujui sebelumnya di sana. Untuk menyetujui tindakan tersebut sebelumnya, letakkan aturan di bawah permissions.allow dalam --settings saat Anda memulai pemimpin. Misalnya, jalankan claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' di shell Anda. Aturan tersebut berlaku untuk pemimpin dan setiap rekan kerja split-pane untuk sesi tersebut.

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.

Konteks dan komunikasi

• Pengiriman pesan otomatis: ketika rekan kerja mengirim pesan, mereka disampaikan secara otomatis kepada penerima. Pemimpin tidak perlu menunggu pembaruan.
• Notifikasi idle: ketika rekan kerja selesai dan berhenti, ia secara otomatis memberi tahu pemimpin dan menyertakan jawaban finalnya dalam notifikasi. Rekan kerja yang gilirannya berakhir pada kesalahan API memberi tahu pemimpin bahwa ia gagal dan menyertakan teks kesalahan.
• Daftar tugas bersama: agent yang memiliki Task tools dapat melihat status tugas dan mengklaim pekerjaan yang tersedia.
• Pesan rekan kerja: kirim pesan ke satu rekan kerja spesifik berdasarkan nama. Untuk menjangkau semua orang, kirim satu pesan per penerima.

Penggunaan token

Contoh use case

Jalankan code review paralel

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.

Investigasi dengan hipotesis bersaing

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.

Best practices

Berikan rekan tim konteks yang cukup

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

• 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

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

Tunggu rekan tim Anda menyelesaikan tugas mereka sebelum melanjutkan

Mulai dengan penelitian dan review

Hindari konflik file

Monitor dan kemudi

Troubleshooting

Rekan tim tidak muncul

• 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

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

• 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.

Terlalu banyak permission prompts

Agents berhenti lebih awal

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

Orphaned tmux sessions

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

Keterbatasan

• 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 subagent background dari rekan tim in-process: subagent milik rekan tim in-process 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. Subagent 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.
• Tidak ada mode izin per-rekan tim saat spawn: rekan tim dimulai dengan mode izin yang dijelaskan di bawah Izin.
• 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

• 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