Skip to main content
Tips Claude Code · Pelajaran 9 dari 13 · 11 menit

Worktree Claude Code: Sesi Paralel Tanpa Bentrok

Jalankan sesi Claude Code paralel dengan git worktree: isi claude --worktree, yang diisolasi, yang tetap dibagi, cara membersihkan, dan isolasi subagent.

Oleh Matthews WongDitinjau pada Dicek dengan Claude Code v2.1.301

Poin utama

Git worktree adalah direktori kerja kedua dengan file dan branch sendiri, yang berbagi satu riwayat repositori. Perintah claude --worktree memberi setiap sesi Claude Code checkout sendiri, sehingga dua sesi bisa mengedit proyek yang sama tanpa saling menimpa. Isolasinya hanya untuk file: riwayat, persetujuan, dan semua yang di luar repositori tetap dipakai bersama.

Setelah pelajaran ini, Anda bisa

  • Memulai sesi paralel yang terisolasi dengan claude --worktree dan tahu di mana letaknya.
  • Menyebut apa yang diisolasi worktree dan apa yang tetap dibagi dengan checkout utama.
  • Memilih antara sesi worktree, subagent biasa, dan subagent dengan isolasi.
Lihat cara kerjanya

Ikuti diagramnya langkah demi langkah

Tekan Putar, atau melangkah dengan panah. Setiap langkah juga ditulis di bawah diagram.

Dua sesi, dua checkout, satu repositori

claude --worktree membuat checkout di bawah .claude/worktrees dengan branch sendiri untuk setiap sesi; edit tetap di direktori itu sementara riwayat .git dipakai bersama, dan saat keluar Claude bertanya apakah worktree yang berisi perubahan ingin disimpan.

Ditinjau pada 17 Oktober 2026 · Claude Code v2.1.301

Langkah 1 dari 7. Git worktree adalah direktori kerja kedua dengan file dan branch sendiri, yang berbagi satu riwayat repositori. Sejauh ini baru ada checkout utama dan .git-nya.

Tombol: ← → langkah · Home / End · K putar atau jeda

  1. Git worktree adalah direktori kerja kedua dengan file dan branch sendiri, yang berbagi satu riwayat repositori. Sejauh ini baru ada checkout utama dan .git-nya.

  2. claude --worktree feature-auth membuat checkout di bawah .claude/worktrees pada branch baru, worktree-feature-auth, lalu memulai sesi di dalamnya.

    claude --worktree feature-auth

  3. Terminal kedua dengan nama berbeda memberi sesi B checkout dan branch sendiri. Kini tiap sesi memegang salinan terpisah dari setiap file yang dilacak.

    claude --worktree bugfixTebak langkah berikutnya Kedua sesi mengedit file yang sama pada saat yang sama. Apakah mereka saling menimpa? (Ya, hanya ada satu file di disk · Tidak, masing-masing punya salinan sendiri)

  4. Edit sesi A hanya masuk ke direktorinya sendiri. Checkout utama dan salinan sesi B tidak tersentuh sampai Anda menggabungkan branch dengan git.

    git worktree list

  5. Semua worktree menulis ke satu direktori .git, jadi commit bertemu di satu repositori. Plugin tingkat proyek dan persetujuan izin yang tersimpan juga dipakai bersama.

    git commit # from inside the worktree

  6. Worktree hanya berisi file yang dilacak. File tak terlacak seperti .env tidak ada dan dependensi belum terpasang, kecuali file .worktreeinclude menyalin file yang diabaikan git.

    .env .env.localTebak langkah berikutnya Anda keluar dari sesi A, yang meninggalkan perubahan belum di-commit. Apa yang terjadi pada worktree-nya? (Dihapus tanpa pemberitahuan · Claude bertanya: simpan atau hapus · Selalu disimpan)

  7. Saat keluar, Claude memeriksa pekerjaan yang ada. Worktree tanpa nama yang bersih dihapus beserta branch-nya; yang berisi perubahan akan bertanya, dan jika disimpan direktori serta branch-nya tetap ada.

    claude --worktree feature-auth --resume

Apa yang dibuat claude --worktree, dan di mana hasilnya?

Git worktree adalah direktori kerja terpisah dengan file dan branch sendiri, yang berbagi riwayat dan remote repositori dengan checkout utama Anda. Beri --worktree, atau -w, sebuah nama, lalu Claude Code membuat satu worktree dan memulai sesi di dalamnya. Secara default hasilnya berada di bawah .claude/worktrees/ di root repositori, pada branch baru bernama worktree- diikuti nama Anda. Jalankan perintah yang sama dengan nama lain di terminal kedua, dan Anda punya dua sesi yang terisolasi. Kalau nama dihilangkan, Claude membuatkan satu.

Baca selengkapnya (2)

Ada tiga prasyarat yang sering terlewat. Repositori harus punya minimal satu commit, karena worktree dibuat dari commit yang sudah ada. Sesi interaktif butuh workspace trust, jadi jalankan claude sekali di direktori itu lebih dulu. Dan dokumentasi menyarankan menambahkan .claude/worktrees/ ke .gitignore agar isinya tidak muncul sebagai file untracked di checkout utama Anda.

Secara default worktree baru bercabang dari branch default repositori di remote, biasanya main, bukan dari branch yang sedang Anda checkout. Atur worktree.baseRef ke "head" di settings agar bercabang dari HEAD lokal Anda saat ini, yang membawa commit yang belum di-push. Untuk memulai dari pull request, beri tanda kutip pada nomornya: claude --worktree "#1234". Kalau nama yang dipakai sudah punya direktori, worktree itulah yang dibuka, bukan yang baru.

Apa yang diisolasi worktree paralel, dan apa yang tetap dibagi?

Worktree mengisolasi file. Selama sesi terisolasi, Claude Code memblokir edit yang menuju path di checkout utama, memblokir perintah shell yang direktori kerjanya berada di sana, dan memblokir perintah git yang dialihkan ke sana. Pemeriksaan yang sama berlaku untuk setiap subagent yang dibuat sesi itu. Pemeriksaan ini hanya membaca path dan teks perintah, jadi cp atau redirect shell yang menulis ke checkout utama tanpa menjalankan git tidak ditolak olehnya. Itu hanya perintah biasa di bawah pengaturan izin dan sandbox Anda.

Baca selengkapnya (2)

Worktree tetap berbagi banyak hal. Setiap worktree menulis ke satu direktori .git milik repositori, itulah sebabnya git commit bisa dijalankan di masing-masing. Plugin yang dipasang di tingkat proyek dimuat di setiap worktree repositori itu. Dan ketika Anda memilih Yes, and don't ask again pada perintah Bash, aturannya disimpan ke .claude/settings.local.json milik checkout utama, sehingga berlaku juga di worktree Anda yang lain dan tetap ada setelah worktree-nya dihapus. Apa pun di luar repositori, seperti folder sementara, port, atau database, memang tidak pernah menjadi bagian dari checkout, jadi dengan sendirinya dipakai bersama.

Dua celah persiapan muncul karena worktree adalah checkout yang masih baru. File untracked seperti .env tidak ada, jadi daftarkan di file .worktreeinclude di root proyek. File itu memakai sintaks .gitignore dan hanya menyalin file yang cocok sekaligus diabaikan git. Dependensi juga belum terpasang, jadi minta Claude menjalankan setup proyek Anda di worktree. Satu detail hook juga penting: setelah Claude masuk ke worktree, CLAUDE_PROJECT_DIR di perintah hook tetap menunjuk ke checkout utama, sedangkan field cwd di JSON input hook mengikuti Claude.

Sesi worktree, subagent, atau keduanya?

Dokumentasi menyebut worktree sebagai salah satu cara menjalankan Claude secara paralel. Worktree mengisolasi edit file, subagent membagi pekerjaan di dalam satu sesi, dan cross-session messaging memungkinkan sesi di worktree berbeda saling mengirim temuan. Ketiganya juga bisa digabung: minta Claude memakai worktree untuk agent-nya, atau atur isolation: worktree di frontmatter subagent kustom, dan setiap run mendapat worktree sementara. Claude Code menghapusnya saat subagent selesai tanpa perubahan. Worktree yang berisi perubahan tetap ada sampai sapuan berkala bisa menghapusnya tanpa kehilangan pekerjaan.

Baca selengkapnya (2)

Repositori ini tidak memakai satu pun dari itu, dan hal itu perlu disebut terus terang. Satu-satunya agent kustomnya, blog-post-author, berjalan di checkout utama tanpa field isolation. Tabrakan dicegah lewat konvensi. Setiap agent menyimpan hasil di folder miliknya sendiri di bawah /tmp/blog-staging, menulis komponen artikelnya sendiri, dan dilarang menyentuh enam file bersama yang hanya ditulis oleh skrip merge. Sesi utama menjadi satu-satunya penulis. Pola ini cocok untuk agent yang menghasilkan draf independen, dan batasnya ditegakkan oleh validator, bukan oleh filesystem.

Patokan saya: pilih sesi worktree ketika dua sesi akan mengedit file terlacak yang sama untuk tujuan berbeda, misalnya fitur di satu terminal dan perbaikan bug di terminal lain. Pilih subagent biasa untuk riset atau draf independen yang digabung oleh satu penulis. Tambahkan isolation: worktree pada subagent ketika ia mengedit file terlacak dan Anda tidak bisa menjamin ia tetap di jalurnya sendiri.

Cara situs ini melakukannya

Konfigurasi nyata di balik pelajaran ini

Kutipan dari repositori yang membangun dan men-deploy situs ini, apa adanya.

.claude/agents/blog-post-author.md:56-58
2. `/tmp/blog-staging/agent-<slug>/registry.json` — an array holding **exactly
   one** descriptor with complete `meta`. Your own folder, never shared: the
   per-post validator rejects a folder containing more than one entry.

Aturan anti-tabrakan untuk agent paralel, ditulis sebagai konvensi. Setiap agent menyimpan hasil di folder bernama slug miliknya sendiri, tidak pernah dipakai bersama, dan validator menolak folder yang berisi lebih dari satu post. Ini isolasi lewat penamaan, bukan lewat worktree: /tmp berada di luar checkout mana pun.

.claude/agents/blog-post-author.md:82-85
- **Do not** run `merge-blog-staging.mjs`, `merge-blog-faqs.mjs`, or any git
  command. The main session merges, generates covers, builds and commits.
- **Do not** edit `messages/en.json`, `messages/id.json`, `lib/blog-*.ts` or
  `[slug]/page.tsx` — the merge script owns those six files.

Aturan satu penulis. File bersama, termasuk kedua file messages, terlarang bagi semua agent, sehingga lima agent yang berjalan bersamaan tidak pernah menulis file yang sama. Worktree akan mengisolasi file repositori; batas ini melakukannya untuk beberapa file yang harus diubah setiap post.

.claude/skills/publishing-blog-posts/SKILL.md:214-216
- **One folder per post**, named for the slug: `agent-epson-escpos`,
  `agent-flutter-permissions`, … The merge reads every `agent-*` folder, so five
  folders is still one merge — and each post keeps its per-post validation.

Cara batch ini berskala. Satu folder per post berarti batch lima post adalah lima folder dan tetap satu merge, karena skrip merge membaca setiap folder agent-*. Fan-out-nya lebar saat menulis draf dan serial pada satu langkah yang menulis file bersama.

Yang sering rusak

Kesalahan yang benar-benar membuang waktu

  • Worktree di repositori yang belum punya commit

    Worktree dibuat dari commit yang sudah ada. Di repositori yang baru dibuat, perintahnya gagal dengan pesan Failed to resolve base branch "HEAD". Buat satu commit lebih dulu.

  • Commit Anda yang belum di-push tidak ada

    Basis default-nya adalah branch default repositori di remote, bukan branch Anda saat ini. Worktree yang dimulai untuk melanjutkan pekerjaan lokal karenanya tidak memuat pekerjaan itu. Atur worktree.baseRef ke "head", atau buat worktree sendiri dengan git worktree add pada branch yang Anda mau.

  • Checkout baru tanpa .env dan tanpa dependensi

    Dev server gagal di worktree baru karena hanya file terlacak yang di-checkout. Pasang dependensi di sana, dan daftarkan file .env di .worktreeinclude agar worktree baru mendapatkannya otomatis.

  • Hook yang mengira root proyek tidak berpindah

    Claude Code menjaga CLAUDE_PROJECT_DIR tetap di checkout utama setelah Claude masuk ke worktree. Perintah hook yang ditulis seperti di repo ini, yang berangkat dari variabel itu, menjalankan salinan skrip milik checkout utama. Kalau skrip butuh path worktree, baca cwd dari JSON input hook. Saya belum menguji hook repo ini di dalam worktree.

  • Yang akan saya ubah di sini: tidak ada yang mengabaikan folder worktree

    .gitignore repositori ini tidak punya entri untuk .claude/worktrees/, dan folder itu belum dipakai saat ini. Sebelum ada yang memulai worktree di sini, tambahkan baris itu, atau setiap worktree akan muncul sebagai file untracked di checkout utama.

Tiga cara bekerja paralel, dan apa yang diisolasi masing-masing
Sesi worktreeFile dan branch, per sesiBelum dipakai
Subagent biasaContext window, bukan fileblog-post-author, dengan folder
Subagent dengan isolation: worktreeContext sekaligus fileTidak diatur di agent mana pun
Coba sendiri

Lakukan di komputer Anda sendiri

Anda butuh Claude Code dan repositori git latihan yang punya minimal satu commit. Anda akan menjalankan dua sesi pada file yang sama, melihat keduanya tetap terpisah, lalu melihat pembersihannya.

  1. Jaga folder worktree tidak muncul di git status, lalu commit perubahan itu agar repositori punya commit untuk dijadikan cabang.

    echo ".claude/worktrees/" >> .gitignore
git add .gitignore && git commit -m "ignore worktrees"

  2. Di satu terminal, mulai sesi di worktree bernama try-a. Di terminal kedua, mulai try-b.

    claude --worktree try-a

# second terminal
claude --worktree try-b

  3. Minta masing-masing sesi menambahkan baris berbeda ke file yang sama, misalnya README.md. Lalu bandingkan dari terminal ketiga.

    git worktree list
git -C .claude/worktrees/try-a diff --stat
git -C .claude/worktrees/try-b diff --stat
git status --short

  4. Keluar dari sesi try-b tanpa mengubah apa pun, dan keluar dari try-a dengan membiarkan editnya belum di-commit. Catat worktree mana yang ditawarkan Claude untuk disimpan.

  5. Buka kembali worktree yang disimpan dengan perintah yang dicetak Claude saat keluar, lalu hapus sendiri kalau sudah selesai.

    claude --worktree try-a --resume

git worktree remove --force .claude/worktrees/try-a
Kuis singkat

Tiga pertanyaan sebelum lanjut

Pilih jawaban untuk melihat kenapa benar atau salah. Tidak ada yang disimpan atau dinilai, jadi tebak saja dengan bebas.

  1. 1.Anda menjalankan claude --worktree feature-auth dengan pengaturan default. Di mana file-nya, dan pada branch apa?
  2. 2.Di worktree yang baru dibuat, npm run dev gagal: tidak ada .env dan tidak ada node_modules. Apa yang terjadi?
  3. 3.Subagent kustom dengan isolation: worktree selesai tanpa mengubah file apa pun. Apa yang terjadi pada worktree sementaranya?
Pikirkan dulu

Jawab dalam hati, lalu cek

  1. 1.Apakah worktree mencegah dua sesi saling menimpa pekerjaan?Lihat jawabannya

    Jawaban:Untuk file di dalam repositori, ya: setiap sesi mengedit salinannya sendiri pada branch sendiri. Pekerjaan itu tetap harus bertemu di git, jadi dua branch yang mengubah baris yang sama akan konflik saat merge. Apa pun di luar repositori tetap dipakai bersama.

  2. 2.Mengapa blog-post-author di repo ini tidak memakai worktree?Lihat jawabannya

    Jawaban:File-file di repo menunjukkan rancangan yang berbeda. Setiap agent menulis komponennya sendiri dan folder staging-nya sendiri, dan enam file bersama hanya ditulis oleh skrip merge di sesi utama. Itu isolasi lewat konvensi ditambah validator. File-file itu tidak menyebut alasan lain.

  3. 3.Bisakah Anda memulai worktree setelah sesi sudah berjalan?Lihat jawabannya

    Jawaban:Bisa. Minta Claude bekerja di worktree dan ia membuatnya dengan tool EnterWorktree. Masuk ke worktree di luar .claude/worktrees meminta persetujuan Anda lebih dulu, karena direktori kerja dan akses tulis sesi berpindah ke sana.

Pelajari lebih dalam

Bahasan mendalam terkait di situs ini

Sumber

Sumber primer yang diperiksa pada tanggal riset. Ikuti tautannya untuk versi terbaru.

Pelajaran sebelumnyaClaude Code Headless: claude -p dengan Gerbang Lulus/GagalPelajaran berikutnyaRewind dan Plan Mode Claude Code: Batalkan Perubahan Berisiko