Jalankan sesi paralel dengan worktrees

​

Mulai Claude dalam worktree

claude --worktree feature-auth

​

Atur lingkungan worktree

​

Minta Claude untuk membuat worktree

​

Claude tidak memiliki tool EnterWorktree

• Sesi interaktif: mulai sesi dalam worktree dengan claude --worktree.
• Sesi latar belakang: Claude Code menolak pengeditan sesi latar belakang di checkout utama Anda hingga sesi tersebut memanggil EnterWorktree, yang tidak dimilikinya. Salah satu dari cara berikut memungkinkan sesi untuk mengedit:
  • Mulai sesi dengan claude --bg --worktree
  • Atur worktree.bgIsolation ke "none"
  • Minta Claude mengedit dalam worktree yang dibuat dengan git worktree add di bawah direktori tempat sesi dimulai

​

Bersihkan worktrees

• Worktree bersih: untuk sesi tanpa nama, Claude menghapus worktree dan cabangnya secara otomatis. Sesi bernama meminta Anda terlebih dahulu sehingga Anda dapat menyimpan worktree untuk nanti
• Worktree memiliki pekerjaan di dalamnya: Claude meminta Anda untuk menyimpan atau menghapus worktree. Menyimpan mempertahankan direktori dan cabang. Untuk kembali nanti, jalankan perintah claude --worktree <name> --resume yang dicetak Claude Code saat keluar. Menghapus menghapus direktori worktree dan cabangnya, bersama dengan semua pekerjaan di dalamnya
• Branch lain sedang di-checkout: jika worktree berada pada branch selain branch miliknya sendiri yang memiliki commit melewati commit awal worktree, Claude meminta Anda untuk menyimpan atau menghapus worktree. Jawaban mana pun tetap menyimpan branch lain tersebut beserta commit-nya. Menghapus menghapus direktori worktree dan branch milik worktree itu sendiri, yaitu branch yang Claude buat bersamanya
• Status worktree tidak dapat diverifikasi: ketika Claude Code tidak dapat menghitung perubahan worktree atau tidak dapat memeriksa checkout submodulnya, Claude meminta Anda daripada menghapus worktree secara otomatis. Prompt tersebut menyebutkan apa yang tidak dapat diperiksa

​

Lanjutkan sesi worktree

• Direktori peluncuran: lanjutkan dengan --resume dari checkout utama atau direktori lain dari repositori. Claude Code memasuki kembali worktree yang dibuat dengan git di bawah .claude/worktrees/ bahkan saat Anda meluncurkan dari dalamnya. Saat Anda meluncurkan dari dalam worktree lain, Claude Code memasuki kembali hanya jika dapat menjaminnya dari sana: worktree yang merupakan repositorinya sendiri, satu tanpa metadata git, atau peluncuran dari subdirektori worktree yang Anda buat dengan git worktree add menolak, jadi luncurkan dari checkout utama.
• --fork-session: sesi yang di-fork dimulai di direktori tempat Anda meluncurkan Claude, dan Claude Code meninggalkan worktree sesi asli tanpa disentuh.
• Worktree yang dihapus: jika direktori worktree tidak lagi ada, Claude Code melanjutkan sesi di direktori tempat Anda meluncurkan Claude. Itu memberi tahu Anda worktree hilang dan menghapus pengikatan worktree sesi.

​

Cara Claude Code menerapkan isolasi

• Pengeditan file: Claude Code memblokir Edit, Write, atau NotebookEdit yang menargetkan path di checkout utama. Untuk mengubah file di checkout utama, edit sendiri file tersebut atau mulai sesi interaktif di sana.
• Direktori kerja perintah: Claude Code memblokir perintah Bash, PowerShell, atau Monitor yang direktori kerjanya di-resolve ke checkout utama, atau yang direktori kerjanya tidak dapat diverifikasi tetap berada di luarnya.
• Pengalihan Git: Claude Code memblokir perintah Bash atau Monitor yang mengalihkan git ke checkout utama. Pengalihan tersebut dapat terjadi melalui git -C, --git-dir, variabel GIT_DIR atau GIT_WORK_TREE, atau cd ke checkout utama sebelum menjalankan git.
• Bentuk perintah: Claude Code memblokir perintah Bash atau Monitor ketika tidak dapat memverifikasi dari teks perintah bahwa setiap git yang dijalankan perintah tersebut tetap berada di dalam worktree. Hal ini terjadi, misalnya, ketika nama perintah dihitung saat runtime, ketika sintaksisnya tidak dapat di-parse, atau ketika ekspansi seperti ${!name} atau ${ command; } dapat menjalankan perintah yang tidak tertulis secara eksplisit dalam teks. Claude Code memberi tahu Claude cara menulis ulang perintah yang ditolak, misalnya dengan memecahnya menjadi perintah-perintah sederhana yang terpisah. Anda tidak dapat mematikan pemeriksaan ini.

​

Isolasi subagents dengan worktrees

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

​

Bersihkan subagent dan worktrees sesi latar belakang

• Worktree masih menyimpan pekerjaan: file yang diubah atau tidak dilacak, atau commit yang belum didorong.
• Submodul yang diperiksa dalam worktree menyimpan file yang diubah atau tidak dilacak, atau Claude Code tidak dapat memeriksa submodul worktree. Pemeriksaan ini memerlukan Claude Code v2.1.274 atau lebih baru.
• Salah satu dari empat kasus yang juga memblokir pembuatan worktree berlaku: Claude Code tidak dapat menentukan driver filter mana yang didefinisikan konfigurasi repositori, atau menemukan pengaturan di sana yang tidak dapat dimatikan.
• Worktree milik sesi --worktree yang belum Anda kirim ke latar belakang, apa pun usianya.
• Anda membuat worktree sendiri dengan git worktree add, bahkan jika Anda kemudian menjalankan sesi --worktree <name> di dalamnya dan mengirimnya ke latar belakang.

​

Kunci worktree dan penghapusan manual

​

Menyesuaikan pembuatan worktree

​

Memilih branch dasar

• "fresh" (default): membuat branch dari branch default repositori di remote, biasanya main, sehingga worktree dimulai dari tree yang bersih dan sesuai dengan remote.
• "head": membuat branch dari HEAD lokal Anda saat ini, sehingga worktree membawa commit Anda yang belum di-push dan status feature branch Anda. Gunakan ini saat mengisolasi subagent yang perlu bekerja pada pekerjaan yang sedang berlangsung. Di dalam worktree, "head" di-resolve ke HEAD milik worktree tersebut, bukan milik checkout utama.

• Jika repositori belum di-fetch dalam 24 jam terakhir, Claude Code melakukan fetch branch default, dibatasi lima detik, dan menggunakan ref yang di-cache secara lokal jika fetch gagal.
• Fetch tidak pernah menunggu input di terminal Anda. Fetch juga dianggap gagal jika git atau ssh akan meminta kata sandi, passphrase kunci, atau konfirmasi host SSH baru.
• Jika tidak ada remote yang dikonfigurasi, atau origin/HEAD tidak di-cache secara lokal dan tidak dapat di-fetch, worktree akan kembali menggunakan HEAD lokal Anda saat ini.

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

​

Membuat branch dari pull request

claude --worktree "#1234"

• github.com: melakukan fetch pull/<number>/head
• gitlab.com: melakukan fetch merge-requests/<number>/head
• GitHub Enterprise, GitLab yang dikelola sendiri, atau host lainnya: mencoba pull/<number>/head terlebih dahulu, lalu merge-requests/<number>/head

​

Menyalin file yang di-gitignore ke worktree

.env
.env.local
config/secrets.json

​

Menggunakan kembali nama worktree

• Worktree tidak memiliki perubahan yang belum di-commit atau file yang tidak dilacak.
• Worktree masih berada di branch yang dibuat Claude Code untuknya.
• Worktree tidak memiliki commit sendiri, atau pull request atau merge request-nya sudah di-merge dan branch remote-nya sudah dihapus.

• Worktree tidak memenuhi salah satu kondisi tersebut.
• Claude Code tidak dapat memverifikasi status worktree.
• worktree.baseRef bernilai "head".
• Nama tersebut merupakan referensi pull request atau merge request.

​

Mengganti pembuatan worktree dengan hook

​

Apa yang dibagikan worktrees dengan checkout utama

• Direktori .git repositori: perintah git dalam worktree menulis ke direktori .git bersama milik repositori utama. Dengan sandbox diaktifkan, perintah seperti git commit bekerja dalam sesi di root worktree, yaitu tempat --worktree memulai sesi. Secara default, perintah tersebut gagal dengan error index.lock jika Anda menjalankan claude di subdirektori worktree.
• Plugins: plugin yang diinstal pada cakupan proyek dari checkout utama juga dimuat dalam worktrees dari repositori yang sama, jadi Anda tidak perlu menginstal ulang per worktree.
• Persetujuan izin: memilih “Yes, and don’t ask again” untuk perintah Bash dalam sesi worktree menyimpan aturan ke .claude/settings.local.json checkout utama. Aturan tersebut berlaku dalam checkout utama dan di setiap worktree lain dari repositori, dan tetap bertahan setelah worktree dihapus. Di Windows dan dalam kasus lain di mana Claude Code tidak menggunakan root repositori, aturan tetap dengan worktree itu. Lihat di mana persetujuan disimpan.
• Skills, agents, dan commands yang tidak dilacak: ketika checkout worktree tidak memiliki direktori .claude/skills di akarnya, misalnya karena .claude/skills Anda diabaikan oleh git, Claude Code memuat project skills checkout utama dalam sesi worktree. Dalam worktree dengan direktori .claude/skills sendiri, hanya salinan itu yang dimuat. Pembacaan yang sama mencakup .claude/agents dan .claude/commands. Untuk skills, pembacaan memerlukan Claude Code v2.1.277 atau lebih baru.

​

Kelola worktrees secara manual

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Non-git version control

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

Pemecahan masalah

​

Claude Code tidak dapat masuk ke worktree saat startup

​

Pembuatan worktree gagal pada path symlink

​

Worktree yang dibuat Claude Code berisi konten asli dari objek yang diganti

​

File Git LFS berupa file pointer di worktree yang dibuat Claude Code

• Could not read the repository git config to neutralize filter drivers: Claude Code tidak dapat membaca .git/config milik repositori, misalnya karena permission-nya. Perbaiki hal tersebut dan coba ulang.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): ganti nama atau hapus filter driver tersebut di .git/config dan coba ulang.
• The repository git config has a conditional include (includeIf): pindahkan pengaturan yang dimuat oleh includeIf di .git/config langsung ke dalam file tersebut, hapus includeIf, dan coba ulang. includeIf di konfigurasi git global Anda tidak memicu hal ini.
• Git was not run: the repository's own git config sets <key>: pesan tersebut menyebutkan key yang mengarahkan Git LFS ke program yang akan dijalankan, seperti lfs.customtransfer.<name>.path atau lfs.standalonetransferagent. Jika pengaturan tersebut milik Anda, pindahkan ke konfigurasi git global Anda. Jika Anda tidak mengenalinya, hapus dari konfigurasi git repositori, karena tool atau checkout yang tidak Anda percayai mungkin telah menulisnya. Coba ulang setelah key tersebut hilang dari konfigurasi repositori.

​

Pembuatan worktree gagal pada partial clone

​

Can only use --worktree in a git repository

• Di folder tanpa version control, jalankan git init di sana, buat commit pertama, lalu coba ulang.
• Di checkout dari sistem version control lain, siapkan hook yang disarankan pesan tersebut.
• Untuk bekerja langsung di direktori tersebut, jalankan Claude tanpa --worktree.

​

Direktori worktree belongs to a different repository

​

Claude Code menolak menggunakan worktree

• Menyebutkan launch from the parent checkout atau Run the resume from the project checkout: Anda menjalankan Claude Code dari dalam worktree. Jalankan dari checkout utama sebagai gantinya; worktree tidak perlu dibuat ulang.
• Menyebutkan it cannot be resumed or re-entered: tidak ada apa pun dalam sesi ini yang menjamin worktree dari lokasi tempat Anda menjalankannya. Buat ulang worktree tersebut; direktori dan pekerjaannya tetap ada di disk untuk pemulihan manual, dan ketika worktree memiliki checkout induk, melanjutkan dari sana juga berhasil.
• Menyebutkan it contains the protected checkout: direktori yang ditolak adalah induk dari checkout utama Anda, seperti direktori home Anda. Jangan menghapusnya. Ubah path worktree, seperti path yang dikembalikan hook WorktreeCreate Anda atau target EnterWorktree, sehingga worktree tidak memuat checkout tersebut.
• Menyebutkan the protected checkout <path> has a .git entry that could not be examined atau has git metadata that could not be resolved: masalahnya ada pada metadata git checkout utama, bukan milik worktree. Jangan menghapus worktree, dan abaikan saran di akhir pesan untuk membuatnya ulang, yang tidak berlaku untuk kedua akhiran ini. Perbaiki checkout utama, misalnya masalah permission atau penolakan git dubious ownership pada .git-nya, lalu coba ulang. Sebelum v2.1.302, dengan git 2.56 atau lebih baru, akhiran could not be resolved juga muncul ketika <path> setelah the protected checkout berisi file .git yang tersesat. Tersesat di sini berarti path pada baris gitdir: file tersebut tidak mengarah ke repositori git yang valid. Untuk memulihkan, perbarui Claude Code dan coba ulang. Ketika path gitdir: tersebut sudah tidak ada, Anda juga dapat menghapus file .git tersebut dan mencoba ulang.
• Menyebutkan its recorded path has a network spelling: Claude Code tidak pernah melanjutkan ke worktree pada path jaringan. Buat ulang worktree di path lokal.
• Akhiran lainnya: pesan tersebut menyebutkan masalah dan perbaikannya, seperti menghapus pengalihan core.worktree atau membuat ulang worktree; ikuti petunjuk tersebut. Sebelum menghapus direktori yang pesannya menyatakan identitas git-nya tidak dapat diverifikasi, atasi terlebih dahulu penyebab yang disebutkan, misalnya symlink di path worktree atau git sendiri yang gagal berjalan, karena direktori tersebut mungkin dalam kondisi baik. Ketika Anda membuat ulang, selamatkan terlebih dahulu perubahan apa pun yang Anda perlukan dari direktori lama; direktori tersebut tetap ada di disk.

​

Sesi dilanjutkan di luar worktree-nya

• Error: cannot resume into worktree <path>: ...This session was not started. untuk penolakan yang ditampilkan tabel sebagai Did not re-enter. Claude Code menghapus pengikatan worktree sebelum keluar, dan error tersebut menyatakannya; saat berikutnya Anda melanjutkan percakapan, sesi berlanjut di direktori saat ini tanpa isolasi worktree. Sebelum v2.1.260, Claude Code tidak menulis pengikatan yang telah dihapus, sehingga setiap percobaan ulang resume yang sama gagal dengan error yang sama. Jika Anda menonaktifkan penulisan transkrip, penghapusan tersebut tidak dapat disimpan. Error tersebut kemudian menyatakan bahwa perintah yang sama akan ditolak lagi, dan menyebutkan --fork-session serta memulai percakapan baru sebagai cara untuk melanjutkan tanpa worktree.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... untuk Could not verify
• Error: ...The worktree binding is kept. untuk Could not re-enter
• Notice: the worktree <path> for this session no longer exists... untuk worktree yang sudah hilang; Claude Code mencetaknya dan melanjutkan sesi, seperti halnya resume interaktif

​

Lihat juga

• Subagents: delegasikan pekerjaan ke agen terisolasi dalam sesi
• Cross-session messaging: biarkan sesi dalam worktrees Anda melewatkan temuan satu sama lain
• Agent teams: koordinasikan beberapa sesi Claude secara otomatis
• Manage sessions: beri nama, lanjutkan, dan beralih antar percakapan
• Jalankan sesi Desktop di worktree-nya sendiri: sesi yang didukung worktree dalam aplikasi desktop