TL;DR: Untuk menjalankan beberapa agen Claude Code secara paralel, berikan git worktree terpisah untuk setiap sesi (cukup dengan satu flag: claude -w <name>), jalankan sesi yang tidak sedang Anda pantau di latar belakang menggunakan claude --bg, dan tentukan urutan merge sebelum agen-agen tersebut selesai, karena branch yang terisolasi pun tetap bisa mengalami konflik saat digabungkan. Dua sesi yang berbagi satu checkout yang sama adalah penyebab commit salah satu agen bisa membawa kode setengah jadi milik agen lainnya. Panduan ini ditujukan bagi developer yang sudah menggunakan Claude Code dan ingin menjalankan dua hingga lima sesi sekaligus.
Semuanya bermula dari terminal kedua. Claude Code sedang merefaktor modul autentikasi di terminal pertama, jadi Anda membuka terminal lain dan meminta sesi baru untuk memperbaiki test tanggal yang flaky. Kemudian terminal ketiga dibuka untuk dokumentasi. Dua puluh menit kemudian, tiga sesi menulis ke direktori kerja yang sama, git status menampilkan file-file yang tidak pernah Anda minta, dan tidak ada yang tahu sesi mana yang menyentuh config.ts.
Menjalankan beberapa agen Claude Code sebenarnya mudah: cukup buka lebih banyak terminal. Namun, menjalankannya tanpa membuat sesi-sesi tersebut merusak pekerjaan satu sama lain membutuhkan tiga keputusan: di mana file setiap sesi disimpan, bagaimana Anda memantau sesi yang sedang tidak Anda lihat, dan urutan branch mereka saat di-merge. Artikel ini membahas ketiganya menggunakan perintah bawaan Claude Code serta dua kegagalan yang kami reproduksi pada sebuah toy repository. Jika Anda belum terbiasa dengan worktree, baca terlebih dahulu panduan git worktree dengan agen coding AI kami, atau referensi git worktree.
Mengapa beberapa agen Claude Code merusak shared checkout
Menjalankan beberapa agen Claude Code secara paralel berarti ada dua atau lebih sesi yang bekerja pada repositori yang sama di waktu bersamaan, masing-masing dengan tugas dan context window-nya sendiri. Sesi-sesi ini tidak mengetahui keberadaan satu sama lain. Masing-masing membaca file, mengeditnya, menjalankan test, dan melakukan commit seolah-olah ia bekerja sendirian.
Sebuah checkout hanya memiliki satu direktori kerja, satu index, dan satu HEAD, sehingga asumsi "bekerja sendirian" akan cepat memicu masalah. Kami mereproduksi skenario yang paling umum terjadi pada repo Python sederhana, dengan dua proses shell writer yang bertindak sebagai agen. Agen B menyimpan fungsi truncate() yang baru setengah jadi ke dalam textutils.py. Agen A menyelesaikan tugasnya sendiri di file yang berbeda dan melakukan commit persis seperti yang diinstruksikan oleh banyak prompt, yaitu dengan git add -A && git commit:
$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
slug.py | 2 ++
textutils.py | 4 ++++
2 files changed, 6 insertions(+)
$ python3 -m pytest -q
1 error in 0.09s
Commit Agen A ikut menyertakan fungsi yang belum selesai milik Agen B, sehingga test suite gagal di-import. Tidak ada kode yang tertimpa secara langsung, tetapi karena index digunakan bersama, commit A ikut menyeret pekerjaan B yang masih berjalan. Akibatnya, riwayat git mencatat bahwa Agen A menulis kode yang rusak. Masalah serupa yang terjadi pada file yang sama dibahas dalam apa yang terjadi ketika dua agen coding mengedit file yang sama.
Jalankan beberapa agen Claude Code dengan satu worktree untuk masing-masing sesi
Solusinya adalah satu direktori kerja untuk setiap sesi, dan Claude Code menyediakannya langsung melalui sebuah flag:
# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux # opens the session in its own tmux or iTerm2 pane
# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"
Berdasarkan dokumentasi worktree, claude -w <name> membuat worktree di .claude/worktrees/<name>/ pada branch baru bernama worktree-<name>, dan terminal kedua dengan nama berbeda akan mendapatkan sesi terisolasi kedua. Saat kami menjalankannya, git menandai worktree baru tersebut sebagai locked, yang mencegah git worktree prune menghapusnya saat sesi masih aktif. Sesi latar belakang yang dimulai dengan --bg atau /bg akan berpindah ke worktree-nya sendiri di dalam .claude/worktrees/ sebelum mengedit apa pun, menurut halaman agent view.
Tiga detail konfigurasi berikut akan menghemat banyak waktu Anda:
- Abaikan foldernya. Worktree berada di dalam repo, sehingga
git statusdi checkout utama akan menampilkan.claude/sebagai untracked sampai Anda menambahkan.claude/worktrees/ke.gitignore, yang juga disarankan oleh dokumentasi. - Siapkan diri untuk checkout baru yang bersih. Worktree baru tidak memiliki
node_modules, virtualenv, ataupun.env. Cantumkan file-file yang di-gitignored dan perlu disalin, seperti.env, ke dalam file.worktreeinclude, serta alokasikan waktu untuk proses instalasi dependensi di setiap worktree. - Bersihkan eksekusi headless sendiri. Sesi interaktif menawarkan opsi untuk menghapus worktree-nya saat keluar. Eksekusi yang dimulai dengan
claude -ptidak pernah melakukan pembersihan otomatis, jadi hapus secara manual menggunakangit worktree unlocklalugit worktree remove.
Sesi latar belakang dikelola langsung dari shell. Deskripsi berikut diambil dari claude --help pada versi 2.1.283:
| Perintah | Fungsi |
|---|---|
claude --bg "<task>" |
Memulai sesi di latar belakang dan langsung kembali ke shell, sambil menampilkan sebuah ID |
claude agents |
Membuka agent view, yaitu daftar sesi yang sedang berjalan (gunakan --json untuk script) |
claude logs <id> |
Menampilkan output terminal terbaru dari sesi latar belakang |
claude attach <id> |
Membuka sesi latar belakang di terminal saat ini |
claude stop <id> |
Menghentikan sesi; riwayat percakapan tetap tersimpan dan dapat dibuka kembali dengan claude attach <id> |
--bg tidak dapat digabungkan dengan -p. Untuk fan-out berbasis script, panduan bekerja dengan Claude Code dari Anthropic mencontohkan shell loop pada claude -p dengan flag --allowedTools dan --permission-mode dontAsk. Gabungkan dengan -w agar setiap eksekusi mendapatkan direktorinya sendiri.
Agen Claude Code yang terisolasi pun tetap bisa bertabrakan saat merge
Worktree mencegah sesi-sesi saling mengganggu saat sedang bekerja, tetapi tidak menjamin hasil kerja mereka kompatibel. Kami mencoba memberikan jenis perubahan yang sama pada dua branch worktree, di mana masing-masing menambahkan satu fungsi di baris akhir textutils.py, lalu kami me-merge keduanya:
$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.
Tidak ada agen yang melakukan kesalahan. Keduanya menambahkan kode di lokasi yang sama dan git tidak bisa menentukan urutannya secara otomatis. Pada codebase nyata dengan empat atau lima sesi, hal ini lumrah terjadi pada file mana pun yang disentuh oleh banyak perubahan: routing table, ekspor __init__.py, changelog, atau lockfile. Bedanya dengan shared checkout, tabrakan ini sekarang terjadi secara jelas, terlihat, dan mudah terlacak sumbernya. Tiga kebiasaan berikut dapat meminimalkan masalah tersebut:
- Bagi tugas berdasarkan file, bukan fitur. Dua tugas yang sama-sama membutuhkan perubahan pada router sebaiknya dijadikan satu tugas, atau dijalankan secara berurutan.
- Lakukan merge dengan urutan yang pasti dan rebase sisanya. Selesaikan branch pertama terlebih dahulu, lalu minta sesi berikutnya melakukan rebase ke
maindan menjalankan kembali pengujiannya sebelum Anda me-review-nya. Sesi yang menulis kode tersebut memiliki konteks untuk menyelesaikan konflik kodenya sendiri. - Beri nama setiap worktree sesuai tugasnya.
claude -w fix-date-testjauh lebih mudah dipahami daripadaclaude -w agent2saat Anda membacagit worktree listsatu jam kemudian.
Batasan terbesarnya biasanya bukan pada git, melainkan Anda yang harus membaca lima diff sekaligus. Artikel kami tentang mengapa review manusia menjadi bottleneck bagi agen paralel membahas cara mengelola antrean review tersebut.
Subagent, agent team, atau sesi terpisah untuk beberapa agen Claude Code
Claude Code kini memiliki beberapa cara untuk menjalankan pekerjaan secara paralel, dan ringkasan agen paralel menjabarkannya berdampingan. Pilihan-pilihan ini tidak dapat saling menggantikan begitu saja. Aspek paling krusial yang membedakannya adalah isolasi:
| Opsi | Apa yang berjalan | Isolasi file | Gunakan ketika |
|---|---|---|---|
| Subagents | Helper di dalam satu sesi, masing-masing dengan context window-nya sendiri | Shared checkout, kecuali jika subagent menyetel isolation: worktree |
Satu tugas memerlukan riset tambahan, proses review, atau pembacaan paralel |
/batch |
Satu perubahan dibagi ke 5 hingga 30 subagent | Satu worktree per subagent | Perubahan mekanis berskala besar yang tersebar di banyak file |
| Agent teams | Sesi utama (lead) ditambah anggota tim (teammates) yang berbagi daftar tugas dan saling berkirim pesan | Tidak ada: dokumentasi menyarankan untuk membagi beban kerja secara mandiri | Anggota tim perlu berkomunikasi di tengah pengerjaan tugas; eksperimental, nonaktif secara default |
Separate sessions (-w, --bg, Desktop) |
Sesi-sesi independen | Satu worktree per sesi | Tugas-tugas independen yang Anda review satu per satu |
Cloud sessions (claude --cloud) |
Sesi di dalam VM terisolasi yang meng-clone branch yang sudah Anda push | Satu VM per sesi | Pekerjaan yang sebaiknya tidak membebani laptop Anda |
Untuk tugas-tugas yang independen, gunakan sesi terpisah dengan worktree. Gunakan agent team ketika bagian-bagian pekerjaan saling bergantung dan anggota tim perlu berkoordinasi, serta pastikan setiap anggota tim menangani file yang berbeda, karena halaman agent teams memperingatkan secara tegas: “Dua rekan tim yang mengedit file yang sama akan menyebabkan penimpaan kode.” Apa pun yang Anda pilih, kuota penggunaan tetap dipakai bersama. Dokumentasi agent view menyatakannya dengan gamblang: “menjalankan sepuluh agen secara paralel menghabiskan kuota sekitar sepuluh kali lebih cepat daripada menjalankan satu agen.”
Peran Sharkly saat Anda menjalankan beberapa agen Claude Code
Jika Anda hanya menjalankan dua atau tiga sesi di laptop sendiri dan me-review setiap diff secara mandiri, perintah-perintah di atas sudah cukup dan Anda mungkin belum membutuhkan Sharkly. Namun, situasinya berubah ketika sesi-sesi tersebut dikerjakan oleh lebih dari satu orang, atau ketika menjawab pertanyaan “sesi mana yang memperbaiki date-test?” membutuhkan waktu lebih lama daripada pengerjaan perbaikan itu sendiri.
Anda sudah memiliki agen coding. Sharkly mengubah mereka menjadi sebuah tim. Setiap bagian pekerjaan menjadi sebuah Task. Anda menugaskannya ke Agent yang berjalan di atas Claude Code Runtime di salah satu Computer Anda, dan menetapkan Assignee akan memulai prosesnya. Dengan direktori kerja default, Create temporary directory, setiap Task mendapatkan direktorinya sendiri dan eksekusi berbasis repositori mendapatkan git worktree yang terisolasi: isolasi yang persis sama dengan claude -w, tanpa perlu repot menamai worktree secara manual. Ketika Agent harus menggunakan kembali environment yang sudah ada di Computer lokal, opsi Run in isolated worktrees akan memberikan hasil setiap Task di branch agent/<agent>/<task> masing-masing. Opsi Max concurrency (assigned tasks) pada Agent membatasi berapa banyak eksekusi yang dapat berjalan bersamaan—yang merupakan batas kapasitas review yang disebutkan sebelumnya, tercatat jelas dan dapat dilihat oleh seluruh tim.
Progres, riwayat eksekusi, dan hasilnya akan kembali ke Task, serta hal apa pun yang membutuhkan intervensi manusia akan masuk ke Inbox. Tidak ada yang di-merge secara otomatis: peninjau manusia akan me-review perubahan di worktree, mempertahankan, me-merge, atau membuangnya, lalu menandai Task sebagai Done. Biaya eksekusi tetap dibebankan ke paket Claude Code Anda sendiri, karena Sharkly tidak menjual token. Halaman fitur Agents menunjukkan cara pengaturannya, dan artikel bagaimana Sharkly menjalankan agen secara paralel membahas sisi eksekusinya secara mendalam.
Jika Anda sudah kewalahan dengan lebih dari tiga terminal dan ingin hasil dari setiap sesi Claude Code terkumpul di satu tempat yang mudah ditinjau, itulah masalah yang dirancang untuk diselesaikan oleh Sharkly.
FAQ
Berapa banyak agen Claude Code yang bisa saya jalankan sekaligus? Dokumentasi resmi tidak menetapkan batas maksimal untuk sesi terpisah. Subagent secara default dibatasi hingga 20 sesi bersamaan, dan halaman agent teams menyarankan untuk memulainya dengan 3 hingga 5 rekan tim. Batasan praktisnya terletak pada kuota penggunaan paket Anda, CPU serta memori laptop Anda, dan seberapa banyak hasil kerja yang sanggup Anda review dalam sehari; perhitungan kapasitas review sangat layak dipertimbangkan sebelum Anda menambahkan sesi keenam.
Apakah sesi Claude Code paralel berbagi batas penggunaan saya? Ya. Pada paket Pro dan Max, batas penggunaan digunakan bersama antara Claude dan Claude Code, dengan jendela lima jam dan batas mingguan, serta setiap sesi paralel menggunakan kuota dari sumber yang sama. Jika ANTHROPIC_API_KEY disetel, tagihan Claude Code akan dialihkan ke API.
Apakah claude --worktree menyalin .env dan dependensi saya? Tidak. Setiap worktree merupakan checkout baru yang bersih. Tambahkan file yang diabaikan git namun Anda butuhkan, seperti .env, ke dalam .worktreeinclude, dan jalankan langkah instalasi dependensi di setiap worktree.
Bisakah saya menjalankan Claude Code dan Codex pada repositori yang sama secara paralel? Bisa, dengan aturan yang sama: satu worktree untuk setiap sesi dan tentukan urutan merge. Panduan kami tentang menjalankan Claude Code dan Codex secara bersamaan di satu codebase membahas aspek routing-nya.
