使用 worktrees 執行平行會話

​

在 worktree 中啟動 Claude

claude --worktree feature-auth

​

設定 worktree 環境

​

要求 Claude 建立 worktree

​

清理 worktrees

• worktree 是乾淨的：對於未命名的會話，Claude 會自動移除 worktree 及其分支。已命名的會話會先提示您，以便您可以保留 worktree 供稍後使用
• worktree 中有工作：Claude 會提示您保留或移除 worktree。保留會保留目錄和分支，以便您稍後可以返回。移除會刪除 worktree 目錄及其分支，以及其中的所有工作
• worktree 的狀態無法驗證：當 Claude Code 無法計算 worktree 的變更或無法檢查其子模組簽出時，它會提示您而不是自動移除 worktree。提示會說明它無法檢查的內容

​

恢復 worktree 會話

• 啟動目錄：從主要檢出或儲存庫的另一個目錄恢復。Claude Code 會重新進入它使用 git 在 .claude/worktrees/ 下建立的 worktree，即使您從其內部啟動。當您從任何其他 worktree 內部啟動時，Claude Code 只有在能夠從那裡為其擔保時才會重新進入它：一個是其自己的儲存庫的 worktree、一個沒有 git 中繼資料的 worktree，或從您使用 git worktree add 建立的 worktree 的子目錄啟動會拒絕，因此請從主要檢出啟動這些。
• --fork-session：分叉的會話在您啟動 Claude 的目錄中啟動，Claude Code 會保持原始會話的 worktree 不變。
• 已刪除的 worktree：如果 worktree 目錄不再存在，Claude Code 會在您啟動 Claude 的目錄中恢復會話。它會告訴您 worktree 已消失並清除會話的 worktree 繫結。

​

Claude Code 如何強制隔離

• 檔案編輯：Claude Code 會阻止針對主要檢出中的路徑的 Edit、Write 或 NotebookEdit。
• 命令工作目錄：Claude Code 會阻止其工作目錄解析為主要檢出的 Bash、PowerShell 或 Monitor 命令，或其工作目錄無法驗證保持在其外的命令。
• Git 重定向：Claude Code 會阻止將 git 重定向到主要檢出的 Bash 或 Monitor 命令。重定向可以透過 git -C、--git-dir、GIT_DIR 或 GIT_WORK_TREE 變數，或在執行 git 之前 cd 到主要檢出。
• 命令形狀：當 Claude Code 無法從命令文字驗證命令執行的任何 git 保持在 worktree 內時，Claude Code 會阻止 Bash 或 Monitor 命令。例如，當命令名稱在執行時計算、語法無法解析，或像 ${!name} 或 ${ command; } 這樣的展開可能執行文字中未明確說明的命令時，就會發生這種情況。Claude Code 會告訴 Claude 如何重寫被拒絕的命令，例如將其分割成純粹的、獨立的命令。您無法關閉此檢查。

​

使用 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.

​

清理子代理和背景會話 worktrees

• worktree 仍然保留工作：已變更或未追蹤的檔案，或未推送的提交。
• worktree 中已簽出的子模組保留已變更或未追蹤的檔案，或 Claude Code 無法檢查 worktree 的子模組。此檢查需要 Claude Code v2.1.274 或更新版本。
• Claude Code 無法確定儲存庫配置定義的篩選驅動程式，或在儲存庫配置中找到它無法關閉的設定，在四個也阻止 worktree 建立的情況中的任何一個適用。
• worktree 屬於您未背景的 --worktree 會話，無論其年齡如何。
• 您自己使用 git worktree add 建立了 worktree，即使您隨後在其中執行了 --worktree <name> 會話並背景了該會話。

​

自訂 worktree 建立

​

選擇基礎分支

• "fresh"（預設）：從遠端上的儲存庫預設分支（通常是 main）分支，因此 worktree 從與遠端相符的乾淨樹開始。
• "head"：從您目前的本地 HEAD 分支，因此 worktree 帶有您未推送的提交和功能分支狀態。當隔離需要在進行中的工作上操作的子代理時，請使用此選項。在 worktree 內，"head" 解析為該 worktree 的 HEAD，而不是主要檢出的。

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

​

從拉取請求分支

claude --worktree "#1234"

• github.com：提取 pull/<number>/head
• gitlab.com：提取 merge-requests/<number>/head
• GitHub Enterprise、自管理 GitLab 或任何其他主機：先嘗試 pull/<number>/head，然後 merge-requests/<number>/head

​

將 gitignored 檔案複製到 worktrees

.env
.env.local
config/secrets.json

​

重複使用 worktree 名稱

• 它沒有未提交的變更或未追蹤的檔案。
• 它仍在 Claude Code 為其建立的分支上。
• 它沒有自己的提交，或其拉取請求或合併請求已合併且其遠端分支已刪除。

• worktree 未通過任何條件。
• Claude Code 無法驗證 worktree 的狀態。
• worktree.baseRef 是 "head"。
• 名稱是拉取請求或合併請求參考。

​

使用 hook 取代 worktree 建立

​

Worktrees 與主要檢出共享的內容

• 儲存庫的 .git 目錄：worktree 中的 git 命令寫入主儲存庫的共享 .git 目錄，沙箱化允許這些寫入，因此 git commit 等命令可以從啟用沙箱的 worktree 內部工作。
• 外掛程式：從主要檢出在專案範圍安裝的外掛程式也會在同一儲存庫的 worktrees 中載入，因此您不需要為每個 worktree 重新安裝它們。需要 Claude Code v2.1.200 或更新版本。
• 權限批准：在 worktree 會話中為 Bash 命令選擇「是，不再詢問」會將規則儲存到主要檢出的 .claude/settings.local.json，因此它適用於主要檢出和儲存庫的每個其他 worktree，並在 worktree 移除後存活。在 Windows 和 Claude Code 不使用儲存庫根目錄的其他情況下，規則會保留在該 worktree 中。在 v2.1.211 之前，在 worktree 中授予的批准被儲存在該 worktree 內，不適用於其他地方，並在 worktree 移除時丟失。請參閱批准的儲存位置。
• 未追蹤的技能、代理程式和命令：當 worktree 檢出在其根目錄沒有 .claude/skills 目錄時（例如因為您的 .claude/skills 被 gitignored），Claude Code 會在 worktree 會話中載入主要檢出的專案技能。在具有自己的 .claude/skills 目錄的 worktree 中，只會載入該副本。 相同的讀取涵蓋 .claude/agents 和 .claude/commands。對於技能，讀取需要 Claude Code v2.1.277 或更新版本。

​

手動管理 worktrees

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

​

非 git 版本控制

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

​

疑難排解

​

Claude Code 無法在啟動時進入 worktree

​

Worktree 建立在符號連結路徑上失敗

​

Git LFS 檔案是 Claude Code 建立的 worktree 中的指標檔案

• Could not read the repository git config to neutralize filter drivers：Claude Code 無法讀取儲存庫的 .git/config，例如因為其權限。修復該問題並重試。
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline)：在 .git/config 中重新命名或移除該篩選驅動程式並重試。
• The repository git config has a conditional include (includeIf)：將 includeIf 在 .git/config 中拉入的設定直接移動到該檔案中，移除 includeIf，然後重試。您全域 git 配置中的 includeIf 不會觸發此問題。
• Git was not run: the repository's own git config sets <key>：訊息命名一個指向 Git LFS 執行程式的金鑰，例如 lfs.customtransfer.<name>.path 或 lfs.standalonetransferagent。如果該設定是您的，將其移動到您的全域 git 設定。如果您不認識它，請從儲存庫的 git 設定中移除它，因為您不信任的工具或檢出可能已寫入它。金鑰從儲存庫的設定中消失後重試。

​

Claude Code 拒絕使用 worktree

• 說 launch from the parent checkout 或 Run the resume from the project checkout：您從 worktree 內部啟動了 Claude Code。改為從主要檢出啟動；worktree 不需要重新建立。
• 說 it cannot be resumed or re-entered：此會話中沒有任何東西從您啟動的地方為 worktree 擔保。重新建立它；目錄及其工作保留在磁碟上以供手動恢復，當 worktree 有父檢出時，從那裡恢復也有效。
• 說 it contains the protected checkout：被拒絕的目錄是您主要檢出的父目錄，例如您的主目錄。不要刪除它。變更 worktree 路徑，例如您的 WorktreeCreate hook 返回的路徑或 EnterWorktree 目標，以便 worktree 不包含檢出。
• 說 the protected checkout <path> has a .git entry that could not be examined 或 has git metadata that could not be resolved：問題是主要檢出的 git 中繼資料，而不是 worktree 的。不要刪除 worktree，忽略訊息的尾部建議重新建立它，這不適用於這兩個結尾。修復主要檢出，例如權限問題或 git 在其 .git 上的 dubious ownership 拒絕，然後重試。
• 說 its recorded path has a network spelling：Claude Code 永遠不會恢復到網路路徑上的 worktree。在本地路徑重新建立 worktree。
• 任何其他結尾：訊息命名問題及其修復，例如移除 core.worktree 重定向或重新建立 worktree；遵循它。在刪除訊息說其 git 身份無法驗證的目錄之前，首先解決命名的原因，例如 worktree 路徑中的符號連結或 git 本身無法執行，因為目錄可能是健康的。當您確實重新建立時，從舊目錄中搶救您需要的任何變更；它保留在磁碟上。

​

會話在其 worktree 外恢復

• Error: cannot resume into worktree <path>: ...This session was not started. 對於表顯示為 Did not re-enter 的拒絕。Claude Code 在退出前清除 worktree 繫結，錯誤說明了這一點；下次您恢復對話時，會話在目前目錄中繼續，沒有 worktree 隔離。在 v2.1.260 之前，Claude Code 沒有寫入清除的繫結，因此同一恢復的每次重試都以相同的錯誤失敗。 如果您抑制記錄寫入，清除無法被儲存。錯誤然後說相同的命令將再次被拒絕，並命名 --fork-session 和啟動新對話作為在沒有 worktree 的情況下繼續的方式。
• Error: could not verify worktree <path> for this resume, so the resume was aborted... 對於 Could not verify
• Error: ...The worktree binding is kept. 對於 Could not re-enter
• Notice: the worktree <path> for this session no longer exists... 對於消失的 worktree；Claude Code 列印它並繼續會話，如互動式恢復所做的

​

另請參閱

• 子代理：在會話內將工作委派給隔離的代理
• 跨會話訊息傳遞：讓您的 worktrees 中的會話相互傳遞發現
• 代理團隊：自動協調多個 Claude 會話
• 管理會話：命名、恢復和在對話之間切換
• 桌面平行會話：桌面應用程式中由 worktree 支援的會話