Git worktree di Claude Code: sesi paralel

Informasi praktis tentang penggunaan Ailoot tersedia di dokumentasi.

Apa itu git worktree di Claude Code#

Menjalankan beberapa agen secara paralel di folder yang sama adalah masalah dasar vibe-coding dengan kecepatan tahun 2026. Agen AI menulis kode lebih cepat daripada kemampuan seseorang untuk mengikuti siapa yang mengubah apa. Tanpa isolasi berkas, menjalankan dua sesi Claude Code secara paralel dalam satu direktori berakhir dengan satu sesi menimpa pekerjaan sesi lainnya.

Git worktree mengatasi masalah ini pada tingkat sistem berkas. Anda memiliki satu direktori utama tempat Anda bekerja. Perintah claude --worktree feature-auth membuat folder .claude/worktrees/feature-auth/ pada branch terpisah dan menjalankan Claude Code di sana. Berkas-berkasnya terisolasi. Perubahan dalam satu sesi tidak terlihat oleh sesi lain sampai Anda secara eksplisit menggabungkannya.

Dokumentasi resmi Anthropic menjelaskannya seperti ini:

Petunjuk untuk mengecek sendiri: jika Anda pernah mendapatkan commit yang separuh berkasnya merupakan pekerjaan orang lain, Anda membutuhkan worktree.

Perbedaan git worktree dengan branch biasa#

Alur Git standar: Anda berada di branch main lalu menjalankan git checkout feature-x—Git menimpa berkas di salinan kerja. npm run dev yang sedang berjalan rusak karena package.json berubah di bawahnya. Anda menyimpan perubahan yang belum di-commit dengan stash dan menunggu IDE mengindeks ulang. Anda kembali, semuanya tertimpa lagi, jadi Anda harus menjalankan stash dan pop lagi.

Git worktree memberi Anda pilihan lain: alih-alih mengganti branch pada satu folder, Anda membuat folder kedua untuk branch lain. Perintah git worktree add ../project-feature-x feature-x membuat direktori ../project-feature-x/ dengan berkas dari branch feature-x. Branch main tetap berada di folder asli, dan server pengembangan terus berjalan.

Sebelumnya, mode worktree di Claude Code harus disiapkan secara manual: git worktree add, lalu cd, lalu claude—dan ulangi di setiap terminal. Flag --worktree (juga -w) melakukan ketiganya dalam satu perintah.

Menjalankan sesi paralel pertama: flag --worktree#

Contoh minimal. Buka terminal pertama di root proyek:

claude --worktree feature-auth

Claude Code melakukan tiga hal:

1. Membuat .claude/worktrees/feature-auth/ dengan snapshot origin/HEAD (biasanya branch default Anda).
2. Membuat branch worktree-feature-auth baru.
3. Menjalankan sesi di folder ini.

Buka terminal kedua di folder root repositori yang sama:

claude --worktree bugfix-123

Selesai. Dua sesi Claude Code, berkas berbeda di disk, branch Git berbeda. Jika Anda menulis autentikasi di sesi pertama dan memperbaiki pengujian yang gagal di sesi kedua, keduanya secara fisik tidak mungkin saling mengganggu.

Jika tidak ingin mengetik nama, Claude akan membuatkannya:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Tips untuk pemula Git: tambahkan .claude/worktrees/ ke .gitignore. Jika tidak, saat menjalankan git status di folder utama, Anda akan melihat isi semua worktree sebagai berkas yang belum dilacak:

# .gitignore
.claude/worktrees/

Kesalahan yang perlu dihindari: sebelum peluncuran --worktree pertama di direktori baru, masuklah dengan claude biasa (tanpa flag) dan setujui dialog kepercayaan ruang kerja. Jika tidak, flag tersebut gagal dengan kesalahan “trust not accepted”—termasuk jika digabungkan dengan -p untuk mode tanpa antarmuka.

Lokasi worktree dan cara menemukannya#

Lokasi default sudah ditetapkan: .claude/worktrees/<value>/ di root repositori. Jika proyek Anda berada di ~/dev/my-app/, worktree feature-auth akan berada di ~/dev/my-app/.claude/worktrees/feature-auth/.

Untuk tata letak nonstandar (misalnya, jika Anda ingin worktree berada di luar repositori), tersedia hook WorktreeCreate—akan dibahas lebih lanjut di bagian tentang SVN dan Mercurial.

Dalam satu sesi Claude, Anda dapat berpindah ke worktree lain yang sudah ada. Cukup tulis di chat: “beralih ke .claude/worktrees/bugfix-123,” dan Claude akan memanggil alat EnterWorktree. Folder saat ini tidak akan berubah—Anda dapat kembali dengan cara yang sama.

Perintah Git standar menampilkan daftar semua worktree, termasuk yang utama dan yang dibuat secara manual:

git worktree list

Keluaran akan terlihat seperti ini:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Menyalin .env dan rahasia: berkas .worktreeinclude#

Saat --worktree membuat folder baru, isinya hanya berkas yang di-commit ke Git. .env yang berisi kunci API dan .env.local yang berisi konfigurasi lokal tercantum di .gitignore, jadi keduanya tidak ada di worktree. Akibatnya, npm run dev pertama kali gagal dengan pesan “MISSING DATABASE_URL.”

Solusi buatan sendiri adalah menyalin .env secara manual setiap kali menjalankan --worktree. Cara ini berhasil sekali, lalu terlupakan. Solusi Anthropic adalah berkas .worktreeinclude di root proyek yang mencantumkan berkas yang diabaikan Git untuk disalin otomatis ke setiap worktree baru.

Buat berkas .worktreeinclude di root repositori:

.env
.env.local
config/secrets.json

Sintaksnya sama dengan .gitignore. Anda dapat menggunakan pola glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic memberikan aturan yang jelas untuk mencegah kecelakaan:

Dengan kata lain, Anda tidak bisa tanpa sengaja menyalin package.json melalui .worktreeinclude—berkas itu tidak ada di .gitignore. Aman untuk menaruh pola apa pun di sana.

.worktreeinclude yang sama berfungsi dalam tiga mode: --worktree manual, worktree otomatis untuk subagen (lihat di bawah), dan sesi dari aplikasi desktop Claude.

Worktree dari pull request untuk tinjauan kode#

Skenario tinjauan kode yang umum: seorang kolega mengirim PR; Anda perlu memeriksa kode, menjalankan pengujian, dan meninggalkan komentar. Dengan git checkout pull/1234/head biasa, Anda kembali mengganti salinan kerja dan mengganggu sesi yang sedang aktif.

Dengan flag --worktree, cukup satu perintah:

claude --worktree "#1234"

Yang terjadi: Claude Code menjalankan git fetch origin pull/1234/head, membuat worktree di .claude/worktrees/pr-1234/, dan melakukan checkout branch PR. Sesi dimulai. Anda dapat langsung memintanya untuk “membaca diff, menjalankan pengujian, dan mencari kesalahan logika”—sementara Claude bekerja, sesi utama Anda di main tetap berjalan.

Sintaks alternatifnya adalah URL pull request lengkap:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Penggunaan dalam proyek nyata: memasangkan claude --worktree "#N" dengan subagen peninjau kode buatan Anda sendiri memberi Anda tinjauan otomatis dalam satu atau dua menit. Jalankan di latar belakang, lanjutkan pekerjaan di jendela utama, lalu lihat hasilnya melalui claude agents.

Branch dasar: worktree.baseRef untuk fresh atau head#

Pengaturan defaultnya seperti ini: setiap worktree baru dimulai dari origin/HEAD. Keuntungannya, Anda mendapatkan awal yang bersih dan pasti sesuai dengan yang akan dilihat CI. Kekurangannya, jika Anda memiliki perubahan yang belum di-commit atau beberapa commit lokal di luar remote pada branch saat ini, perubahan itu tidak akan disertakan dalam worktree baru.

Untuk memulai worktree dari commit HEAD lokal saat ini, tambahkan ini ke .claude/settings.json (atau pengaturan global):

{
  "worktree": {
    "baseRef": "head"
  }
}

Kini claude --worktree experimental-feature dimulai dari HEAD lokal saat ini. Ini berguna ketika fitur sudah memiliki commit lokal yang belum di-push. Pengaturan tidak menyertakan edit terlacak yang masih belum di-commit. Jika subagent memerlukan edit itu, simpan dan pindahkan perubahan yang diperlukan secara eksplisit, lalu periksa diff tujuan; jangan campuradukkan pemindahan tersebut dengan .worktreeinclude, yang menangani file lokal diabaikan.

Pengaturan ini menerima tepat dua nilai: "fresh" (= origin/HEAD) dan "head" (= HEAD lokal). Ref arbitrer seperti "feature-branch" atau hash commit tidak dapat digunakan—ini pembatasan yang disengaja untuk mencegah ledakan kombinasi pilihan.

Mengisolasi subagen secara otomatis: isolation: worktree#

Saat Anda meminta Claude “jalankan tiga subagen: yang satu membaca basis data, yang kedua memeriksa API, dan yang ketiga memeriksa pengujian,” secara default ketiganya bekerja di salinan kerja Anda. Jika bahkan dua di antaranya menulis ke berkas yang sama pada saat bersamaan, akan terjadi konflik. Solusinya adalah memberikan worktree sendiri secara otomatis kepada masing-masing.

Metode 1: minta secara lisan. Tulis kepada Claude dalam percakapan:

Gunakan worktree untuk agen-agen Anda.

Claude akan menerapkan isolasi pada semua subagen berikutnya dalam sesi ini.

Metode 2: atur secara eksplisit pada subagen itu sendiri. Di berkas subagen (misalnya, .claude/agents/code-reviewer.md), tambahkan field ke frontmatter:

---
name: code-reviewer
description: Membaca diff dan menulis komentar tinjauan kode
isolation: worktree
---

Kamu adalah reviewer yang teliti. Baca diff dan cari kesalahan logika...

Kini setiap peluncuran subagen ini mendapatkan worktree sementara di .claude/worktrees/. Jika subagen tidak menulis apa pun, folder akan dihapus otomatis saat subagen selesai. Jika ada perubahan yang belum di-commit, Claude akan bertanya apakah Anda ingin menyimpannya atau menghapusnya.

Branch dasar untuk worktree subagen sama dengan --worktree: secara default, origin/HEAD; dengan worktree.baseRef: head, HEAD lokal.

Matriks keputusan: worktree, /bg, subagen, atau Agent View#

Kombinasi yang umum:

• “2 fitur secara paralel, manual” — dua terminal, masing-masing menjalankan claude --worktree. Kasus paling sederhana.
• “Jalankan refaktor semalaman; saya akan menutup aplikasi” — /bg + /goal dengan kondisi penyelesaian. Sesi berjalan terlepas dari jendela Anda.
• “Satu prompt, tiga penyelidikan paralel” — tiga subagen dengan isolation: worktree. Masing-masing berada di sandbox sendiri.
• “Apa yang sedang berjalan sekarang?” — claude agents. Dasbor semua sesi dengan filter “running,” “blocked,” dan “done.”

5 jebakan saat bekerja dengan worktree#

1. Menjalankan worktree, .env hilang, tidak ada yang berfungsi. Ini masalah paling umum. Worktree adalah checkout baru tanpa berkas yang diabaikan Git. Solusinya adalah menambahkan berkas .worktreeinclude berisi .env* dan konfigurasi lokal yang diperlukan segera setelah menyiapkan mode worktree. Pastikan berkasnya berada di root repositori, bukan di .claude/.

2. Anda ingin berpindah ke branch utama, menjalankan cd ke root, lalu kehilangan perubahan yang belum di-commit di worktree. Folder root dan worktree adalah dua salinan kerja yang berbeda. Anda kembali dengan cd; perubahan di worktree tetap berada di tempatnya—tidak hilang. Namun jika Anda bingung lalu menjalankan git stash di folder utama, karena mengira sedang berada di worktree, stash akan dibuat di branch utama, bukan branch yang Anda maksud.

3. Menjalankan 5 sesi paralel lalu tidak ingat apa yang sedang dikerjakan masing-masing. Dokumentasi Anthropic secara eksplisit memperingatkan bahwa kebanyakan pengembang secara kognitif tidak mampu menangani lebih dari 2–3 sesi. Tanda kelebihan beban adalah membuka Agent View dan tidak dapat langsung mengatakan apa yang sedang dikerjakan setiap agen. Batasi diri Anda pada dua sesi bersamaan. Jika tugas membutuhkan lebih banyak, tugas tersebut sebaiknya diorkestrasi melalui /goal + subagen, bukan secara manual.

4. Worktree dari -p (tanpa antarmuka) tidak dibersihkan secara otomatis. Perintah claude --worktree feature-x -p "do thing" tidak menampilkan prompt keluar interaktif, jadi tidak ada momen ketika Claude bertanya “hapus worktree?” Worktree ini akan menumpuk. Bersihkan secara manual: git worktree remove .claude/worktrees/feature-x. Atau gunakan skrip cron yang menghapus apa pun yang berusia lebih dari 7 hari.

5. Dialog kepercayaan di folder baru. Jika Anda membuka repositori untuk pertama kali lalu langsung menjalankan claude --worktree, perintah akan gagal. Jalankan claude tanpa flag, setujui kepercayaan ruang kerja, lalu keluar—setelah itu --worktree akan berfungsi. Ini disengaja agar Claude tidak mendapatkan akses ke proyek orang lain tanpa persetujuan pengguna.

Pembersihan: apa yang dihapus secara otomatis#

Logika pembersihan bergantung pada apa yang telah Anda lakukan di worktree dan bagaimana Anda memulai sesi. Dokumentasi Anthropic menyebutkan tiga skenario:

Skenario 1: Anda masuk, tidak melakukan apa pun, lalu keluar—worktree dihapus.

Skenario 2: Anda mengerjakan sesuatu dan tidak melakukan commit—Claude akan bertanya “simpan atau hapus?” saat Anda keluar. “Simpan” mempertahankan folder dan branch untuk nanti. “Hapus” menghapus direktori beserta perubahan yang belum di-commit dan commit baru. Tindakan ini destruktif—jangan klik “hapus” karena kebiasaan.

Skenario 3: Anda menjalankan dengan -p (tanpa antarmuka), lalu perintah selesai dan keluar. Worktree tetap ada. Bersihkan secara manual:

git worktree remove .claude/worktrees/feature-x

Selain itu, worktree dari sesi subagen dan /bg otomatis dihapus oleh pembersihan latar belakang jika usianya melebihi cleanupPeriodDays hari (sebuah pengaturan, biasanya 30 hari secara default) dan tidak memiliki pekerjaan yang belum disimpan. Worktree dari --worktree tidak disentuh oleh pembersihan otomatis—tanggung jawab Anda untuk mengelolanya.

Alternatif untuk SVN, Perforce, dan Mercurial: hook WorktreeCreate#

Jika repositori menggunakan Subversion atau Mercurial, flag --worktree tidak akan berfungsi secara langsung. Anthropic menyediakan titik ekstensi melalui dua hook: WorktreeCreate (membuat salinan terisolasi) dan WorktreeRemove (menghapusnya).

Contoh hook SVN dari dokumentasi resmi:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Hook membaca nama worktree dari stdin ({ "name": "feature-auth" }), menjalankan svn checkout ke direktori yang telah ditentukan sebelumnya, dan mencetak path ke stdout—Claude Code menggunakannya sebagai direktori kerja untuk sesi baru.

Catatan penting: saat menggunakan hook sendiri, .worktreeinclude tidak digunakan. Jika Anda memerlukan .env atau berkas lain yang diabaikan Git di folder baru, salin berkas tersebut di dalam skrip hook.

Selanjutnya: tiga mekanisme paralelisme yang berkaitan#

Worktree memberi Anda isolasi berkas. /bg memberi Anda isolasi konteks. Subagen memberi Anda isolasi tugas. Setiap mekanisme menyelesaikan satu masalah secara mandiri. Jika digabungkan, semuanya memberi cara untuk mengerjakan tiga hingga lima tugas paralel tanpa kehilangan kendali. Inilah keterampilan di balik vibe-coding tingkat lanjut pada 2026.

Topik ini berlanjut secara alami ke tiga bahasan terkait: cara menyiapkan agen otonom menggunakan /goal dan Agent View, cara membuat subagen sendiri untuk tugas Anda, dan cara menjalankan ratusan agen melalui Dynamic Workflows.

Kunjungi Ailoot.