使用 worktrees 執行平行會話
在獨立的 git worktrees 中隔離平行的 Claude Code 會話，使變更不會相互衝突。涵蓋
--worktree旗標、子代理隔離、.worktreeinclude、清理和非 git VCS hooks。
git worktree 是一個獨立的工作目錄，具有自己的檔案和分支，但與主要檢出共享相同的儲存庫歷史記錄和遠端。在自己的 worktree 中執行每個 Claude Code 會話意味著一個會話中的編輯永遠不會觸及另一個會話中的檔案，因此您可以讓 Claude 在一個終端中建置功能，同時在第二個終端中修復錯誤。
本頁涵蓋 CLI 中的 worktree 隔離。下面的所有內容都假設使用 git 儲存庫。對於其他版本控制系統，請參閱非 git 版本控制。桌面應用程式會自動為每個新會話建立一個 worktree。
Worktrees 是執行 Claude 平行處理的幾種方式之一。它們隔離檔案編輯，而子代理和代理團隊協調工作本身。請參閱平行執行代理以比較這些方法，或跳到使用 worktrees 隔離子代理以同時使用 worktrees 和子代理。
在 worktree 中啟動 Claude
傳遞 --worktree 或 -w 以建立隔離的 worktree 並在其中啟動 Claude。預設情況下，worktree 在您的儲存庫根目錄下的 .claude/worktrees/<value>/ 下建立，在名為 worktree-<value> 的新分支上：
claude --worktree feature-auth
要將 worktrees 放在其他地方，請配置 WorktreeCreate hook。在另一個終端中使用不同的名稱再次執行該命令以啟動第二個隔離的會話：
claude --worktree bugfix-123
如果您省略名稱，Claude 會生成一個名稱，例如 bright-running-fox：
claude --worktree
您也可以在會話期間要求 Claude「在 worktree 中工作」，它將使用 EnterWorktree 工具建立一個。進入 worktree 後，Claude 可以透過呼叫 EnterWorktree 並指定目標路徑，直接切換到 .claude/worktrees/ 下的另一個 worktree。前一個 worktree 保持在磁碟上未被觸及。
在第一次在目錄中使用 --worktree 之前，請透過在該目錄中執行一次 claude 來接受工作區信任對話。如果尚未接受信任，--worktree 將以錯誤退出並提示您先在目錄中執行 claude。非互動式執行搭配 -p 會跳過信任檢查，因此 claude -p --worktree 會在沒有信任檢查的情況下進行。
選擇基礎分支
Worktrees 從您的儲存庫的預設分支 origin/HEAD 分支，因此它們從與遠端相符的乾淨樹開始。如果未配置遠端或提取失敗，worktree 會回退到您目前的本地 HEAD。要始終從本地 HEAD 分支，請在設定中將 worktree.baseRef 設定為 "head"。將 baseRef 設定為 "head" 會使新 worktrees 帶有您未推送的提交和功能分支狀態，這在隔離需要在進行中的工作上操作的子代理時很有用。該設定僅接受 "fresh" 或 "head"，不接受任意 git refs：
{
"worktree": {
"baseRef": "head"
}
}
要從特定的拉取請求分支，請傳遞以 # 為前綴的 PR 編號或完整的 GitHub 拉取請求 URL。Claude Code 從 origin 提取 pull/<number>/head 並在 .claude/worktrees/pr-<number> 建立 worktree：
claude --worktree "#1234"
為了完全控制 worktrees 的建立方式，請配置 WorktreeCreate hook，它完全取代預設的 git worktree 邏輯。
將 gitignored 檔案複製到 worktrees
Worktree 是一個新的檢出，因此來自您主要儲存庫的未追蹤檔案（如 .env 或 .env.local）不存在。要在 Claude 建立 worktree 時自動複製它們，請將 .worktreeinclude 檔案新增到您的專案根目錄。
該檔案使用 .gitignore 語法。只有符合模式且也被 gitignored 的檔案才會被複製，因此追蹤的檔案永遠不會被重複。
此 .worktreeinclude 將兩個環境檔案和一個秘密配置複製到每個新 worktree：
.env
.env.local
config/secrets.json
這適用於使用 --worktree 建立的 worktrees、子代理 worktrees 和桌面應用程式中的平行會話。
使用 worktrees 隔離子代理
子代理可以在自己的 worktrees 中執行，以便平行編輯不會衝突。要求 Claude「為您的代理使用 worktrees」，或通過將 isolation: worktree 新增到 frontmatter 在自訂子代理上永久設定它。每個子代理都會獲得一個臨時 worktree，當子代理完成而沒有變更時會自動移除。
子代理 worktrees 使用與 --worktree 相同的基礎分支，因此它們從您的儲存庫的預設分支分支，除非 worktree.baseRef 設定為 "head"。
清理 worktrees
當您退出 worktree 會話時，清理取決於您是否進行了變更：
- 無未提交的變更、無未追蹤的檔案且無新提交：worktree 及其分支會自動移除。如果會話有名稱，Claude 會改為提示您，以便您可以稍後保留 worktree
- 存在未提交的變更、未追蹤的檔案或新提交：Claude 會提示您保留或移除 worktree。保留會保留目錄和分支，以便您稍後可以返回。移除會刪除 worktree 目錄及其分支，丟棄所有未提交的變更、未追蹤的檔案和提交
- 非互動式執行：使用
--worktree與-p一起建立的 worktrees 不會自動清理，因為沒有退出提示。使用git worktree remove移除它們
Claude 為子代理和背景會話建立的 Worktrees 一旦超過您的 cleanupPeriodDays 設定，就會自動移除，前提是它們沒有未提交的變更、沒有未追蹤的檔案和沒有未推送的提交。您使用 --worktree 建立的 Worktrees 永遠不會被此掃描移除。
當代理正在執行時，Claude 會在其 worktree 上執行 git worktree lock，以便並行清理無法將其移除。當代理完成時，鎖定會被釋放。若要清理掃描保留的 worktree，請執行 git worktree remove，如果 worktree 有未提交的變更或未追蹤的檔案，請新增 --force。
手動管理 worktrees
為了完全控制 worktree 位置和分支配置，請直接使用 Git 建立 worktrees。當您需要檢出特定的現有分支或將 worktree 放在儲存庫外時，這很有用。
在新分支上建立 worktree：
git worktree add ../project-feature-a -b feature-a
從現有分支建立 worktree：
git worktree add ../project-bugfix bugfix-123
在 worktree 中啟動 Claude：
cd ../project-feature-a && claude
列出您的 worktrees：
git worktree list
完成後移除一個：
git worktree remove ../project-feature-a
有關完整的命令參考，請參閱 Git worktree 文件。記住在每個新 worktree 中初始化您的開發環境：安裝依賴項、設定虛擬環境或執行您的專案設定所需的任何操作。
非 git 版本控制
Worktree 隔離預設使用 git。對於 SVN、Perforce、Mercurial 或其他系統，請配置 WorktreeCreate 和 WorktreeRemove hooks 以提供自訂建立和清理邏輯。因為 hook 取代了預設的 git 行為，當您使用 --worktree 時，.worktreeinclude 不會被處理。改為在您的 hook 指令碼內複製任何本地配置檔案。
此 WorktreeCreate hook 從 stdin 讀取 worktree 名稱，檢出新的 SVN 工作副本，並列印目錄路徑，以便 Claude Code 可以將其用作會話的工作目錄：
{
"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\"'"
}
]
}
]
}
}
將其與 WorktreeRemove hook 配對以在會話結束時進行清理。有關輸入架構和移除範例，請參閱 hooks 參考。
另請參閱
Worktrees 處理檔案隔離。下面的相關頁面涵蓋將工作委派到這些隔離的檢出中以及在您建立的會話之間切換：