Jawaban singkat untuk pertanyaan yang paling sering diajukan pembaca tentang topik ini.
Agent teams memberi setiap teammate context window sendiri, mailbox, dan satu task list bersama. Ini cara mengaktifkannya, mengunci dengan hook, dan biayanya.
Matthews Wong
Software Engineer
Ringkasan Utama
Claude Code agent teams menjalankan beberapa sesi Claude penuh sekaligus di bawah satu lead. Setiap teammate memegang context window sendiri, saling berkirim pesan lewat file mailbox, dan mengambil pekerjaan dari task list bersama yang dilindungi file locking. Fitur ini masih experimental dan mati secara default sampai Anda menyetel CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ke 1.
Saya pernah punya bug yang selamat dari tiga sesi terpisah. Masing-masing menemukan penyebab yang masuk akal, menulis perbaikan yang masuk akal, dan meninggalkan gejalanya persis di tempat semula. Sesi keempat saya jalankan berbeda: saya minta lima teammate, memberi tiap orang satu hipotesis berbeda, lalu menyuruh mereka berdebat. Dua teori mati dalam empat menit karena teammate lain bisa menunjuk kode yang membantahnya.
Itulah bentuk pekerjaan yang benar-benar cocok untuk agent teams. Tulisan ini membahas cara mengaktifkannya, bedanya dengan subagent sampai ke titik yang bisa merusak orkestrasi kalau Anda menganggap keduanya sama, di mana tim itu tersimpan di disk, cara mengunci teammate dengan hook, dan batasan yang layak Anda tahu sebelum menyerahkan satu refactor ke sebuah tim.
Agent teams masih experimental. Tanpa environment variable itu disetel, tidak ada direktori tim yang ditulis saat sesi dimulai dan Claude tidak akan memunculkan teammate bagaimanapun Anda menyusun kalimatnya. Variabel ini dibaca dari settings.json atau dari shell Anda, dan Claude Code membacanya ulang setiap kali memunculkan subagent, jadi Anda bisa mengubahnya di tengah sesi dan spawn berikutnya sudah memakai nilai yang baru.
Bagian yang mengejutkan adalah efek sampingnya. Selama teams aktif, subagent apa pun yang diberi nama oleh Claude akan diluncurkan sebagai teammate, bukan sebagai subagent. Claude memberi nama pada subagent atas inisiatifnya sendiri supaya bisa mengirim pesan ke sana nanti, sehingga sebuah tim bisa terbentuk pada delegasi yang tidak pernah Anda maksudkan sebagai kerja tim.
// ~/.claude/settings.json
// Agent teams are experimental and OFF by default. Without this
// variable no team directory is written and Claude never spawns
// a teammate, however you phrase the prompt.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
// "in-process" (default) keeps every teammate in one terminal.
// "auto" opens split panes when tmux or iTerm2 + it2 is present.
"teammateMode": "in-process"
}Subagent mengembalikan hasilnya ke Claude. Teammate hanya mengirim notifikasi idle yang mengabarkan bahwa ia berhenti, tanpa isi hasilnya. Alur orkestrasi yang menunggu hasil subagent karena itu akan macet tanpa suara begitu agent teams menyala. Kalau itu terjadi, setel variabelnya ke 0 di user settings dan subagent bernama berikutnya kembali diluncurkan sebagai subagent.
Keduanya memberi Anda lebih dari satu agent, dan di situlah kemiripannya berhenti. Subagent adalah pekerja yang dipanggil, diawasi, dan dipanen hasilnya oleh main agent. Teammate adalah sesi setara yang berbicara dengan sesama teammate dan mengambil pekerjaannya sendiri. Salah memilih membuat Anda membayar koordinasi yang tidak dibutuhkan, atau kehilangan koordinasi yang justru dibutuhkan.
Empat perbedaan yang benar-benar menentukan mana yang sebaiknya Anda pakai:
| Dimensi | Subagent | Agent teams |
|---|---|---|
| Komunikasi | Mengembalikan satu hasil ke pemanggil | Teammate saling berkirim pesan langsung lewat nama |
| Koordinasi | Main agent mengatur seluruh pekerjaan | Koordinasi mandiri plus task list bersama yang bisa dikunci |
| Paling cocok untuk | Tugas terfokus yang hanya hasilnya penting | Pekerjaan yang butuh diskusi dan perbedaan pendapat |
| Biaya token | Lebih rendah — hasil diringkas kembali | Lebih tinggi — tiap teammate satu instance Claude utuh |
Anda tidak lagi membuat tim sebagai langkah terpisah. Tool TeamCreate dan TeamDelete dihapus di v2.1.178, dan pembersihan terjadi otomatis saat sesi berakhir. Anda cukup menjelaskan peran yang diinginkan dan lead akan memunculkannya. Selalu beri nama di dalam prompt: lead memberi nama pada setiap teammate yang ia buat, dan nama itulah yang dipakai teammate lain untuk mengirim pesan. Kalau Anda membiarkan lead mengarang nama, Anda tidak bisa merujuk teammate tertentu di instruksi berikutnya.
# The lead spawns teammates from plain language. Name them —
# the name is the address other teammates send messages to.
Spawn three teammates to review PR #142:
- security : token handling, session management, input validation
- perf : N+1 queries and allocation in the hot path
- tests : coverage of the new branches only
Have them message each other with anything the others should
re-check, then report to me.
# Agent panel keys (in-process mode):
# up / down select a teammate
# Enter open its transcript and type to message it
# x stop the selected teammate
# Ctrl+T toggle the shared task list
# Esc interrupt the selected teammate's current turnSpawning butuh sesi interaktif. Dalam mode non-interaktif dengan flag -p, termasuk sesi Agent SDK, Claude tidak memunculkan teammate dan subagent bernama tetap berjalan sebagai subagent biasa walau fiturnya aktif. Teammate juga mewarisi permission mode milik lead saat dibuat, dan Anda tidak bisa menetapkan mode per teammate pada saat spawn — hanya sesudahnya.
Tim bukan abstraksi yang hidup di kepala model. Ia adalah sebuah direktori, dan menyadari itu mengubah sebagian besar proses debug tim menjadi sekadar membaca file. Nama tim diturunkan dari sesi: string session- diikuti delapan karakter pertama dari session id.
# Where a team actually lives on disk. The name is
# "session-" plus the first eight characters of the session id.
~/.claude/teams/session-a1b2c3d4/config.json # members, agent ids, pane ids
~/.claude/teams/session-a1b2c3d4/inboxes/*.json # one mailbox per agent
~/.claude/tasks/session-a1b2c3d4/ # the shared task list
# config.json holds live runtime state — do not hand-author it.
# The teams directory is removed when the session exits; the tasks
# directory persists, so a resumed session keeps its task list.Mailbox tiap agent adalah file JSON, dan Claude Code memvalidasi setiap entri saat membacanya. Entri yang tidak sesuai format pesan dilaporkan lalu dihapus, dan pesan yang valid tetap terkirim. Sebelum v2.1.207, satu entri rusak saja memicu error berulang setiap detik dan memblokir pengiriman untuk mailbox itu sampai Anda menghapus filenya manual. Sebuah pesan baru dilaporkan terkirim ketika penulisan ke mailbox penerima benar-benar berhasil, jadi disk penuh berarti pengirim menerima error, bukan pesan yang hilang diam-diam.
Kegagalan yang paling sering saya temui adalah teammate yang memutuskan pekerjaannya selesai padahal type-check masih merah. Ada tiga hook yang menyala pada event siklus hidup tim, dan ketiganya memakai konvensi yang sama: keluar dengan exit code 2 untuk menolak transisi dan mengirim teks stderr Anda kembali ke agent sebagai umpan balik.
// .claude/settings.json — a teammate that says it is done
// but left the type-check red goes back to work. Exit code 2
// sends the stderr text back as feedback and keeps it running.
{
"hooks": {
"TeammateIdle": [
{
"hooks": [
{
"type": "command",
"command": "npx tsc --noEmit || { echo 'tsc is red — fix it before going idle' >&2; exit 2; }"
}
]
}
]
}
}Pemakaian token naik kira-kira linier terhadap jumlah teammate aktif, karena masing-masing adalah context window terpisah yang membaca file sendiri. Panduan Anthropic sendiri menyarankan mulai dari tiga sampai lima teammate untuk sebagian besar workflow, dengan lima atau enam task per teammate — tiga teammate yang fokus rutin mengalahkan lima yang berpencar, dan setelah titik tertentu tambahan teammate berhenti mempercepat apa pun sambil tetap menagih penuh.
Ada biaya kedua yang kurang kelihatan. Request dari teammate in-process berada di luar bucket prompt cache milik percakapan utama, jadi cache-nya hanya bertahan lima menit secara default, bukan satu jam, bahkan pada langganan berbayar. Pada tim yang berpikir agak lama di antara giliran, itu berarti Anda membayar pemrosesan ulang prefix berkali-kali.
Setel subagentPromptCacheTtl ke 1h di settings.json sebelum menjalankan tim untuk waktu lama. API menagih cache write satu jam dengan tarif lebih tinggi, jadi ini memang trade-off nyata — tetapi pada sesi lima teammate dengan jeda panjang antar giliran, sisi itu selalu jadi yang lebih murah buat saya.
Agent teams diberi label experimental dan label itu memang berarti. Ini batasan yang mengubah cara saya memakainya:
Aturan yang akhirnya saya pakai sengaja dibuat sempit: pakai tim ketika nilainya datang dari perbedaan pendapat, dan pakai subagent ketika nilainya datang dari jawabannya. Review paralel, hipotesis yang saling bersaing, dan pekerjaan lintas lapisan semuanya diuntungkan oleh teammate yang bisa saling menantang. Apa pun yang berurutan, apa pun yang menyentuh file yang sama, dan apa pun yang cuma butuh ringkasan kembali akan lebih murah dan lebih andal sebagai subagent.
Sumber & bacaan lanjutan