AGENT

Claude Code原生Git Worktree

这感觉像魔法，我现在可以并行运行多个代理而不必担心它们互相踩脚。

admin

Mar 1, 2026 • 10 min read

AI编程/Vibe Coding 遇到问题需要帮助的，联系微信 ezpoda，免费咨询。

这感觉像魔法，我现在可以并行运行多个代理而不必担心它们互相踩脚。

忘记合并冲突和阻塞功能的噩梦；你不再需要等待一个分支稳定后再开始另一个。

我在它发布后立即进行了测试，我想带你了解它是如何工作的以及你今天如何设置它。

但首先，你需要理解 Claude Code 的原生 Git worktree 解决什么问题。

1、一次运行一个代理的问题

在工作树之前，如果你同时构建多个功能，你有两个选择。

第一种是将所有内容倾倒到一个提示词中。"添加暗黑模式、设置本地存储持久化并添加内联编辑。"Claude 会开始工作，如果这三件事中的任何一件事有 bug，你的整个分支将被阻塞。
第二种选择是手动管理单独的分支；创建分支、切换上下文、开始新会话、失去你的流程、重复。这不是你期望的代理工作流的流畅并行体验。

如果你经历过这个问题，你会理解随着项目的变大情况会变得更糟。

另一个担忧是在现实世界的项目管理中；功能不会彼此等待。

示例：常见的情况是你在调试一件事的同时构建另一件事，并审查第三件事。你的代理不应该在单文件或单分支车道中工作。

这就是问题，Claude Code 原生 Git worktree 解决了。

2、什么是 Git Worktree？

在我们进入 Claude Code 端的东西之前，让我给你一个关于 worktree 是什么的基本知识 —— 因为名称经常令人困惑。

git worktree 不是单独的仓库。它是链接到同一仓库的单独工作目录。每个 worktree 都有自己的签出分支、自己的 HEAD 和自己的工作文件 —— 但它们都共享相同的 git 历史和对象。

更简单的例子：

你的主项目文件夹是办公室里的办公桌
Worktree 是同一个办公室里的第二张办公桌

两张办公桌都有自己的纸张和工具，但它们都从同一个文件柜里拉取。

对于 Claude Code，这意味着每个代理都在自己的隔离环境中工作。

一个代理正在 feature/auth 上构建你的身份验证功能
另一个正在 fix/payment-bug 上修复错误

它们不接触相同的文件，也不等待彼此。

开始之前需要知道的关键事项：

你的项目必须初始化 git（git init）
在 worktree 工作之前，你需要在主分支上至少有一个提交
每个 worktree 签出一个唯一的分支 —— 两个 worktree 不能同时共享同一个分支
当你完成后，你可以保留 worktree 或删除它。

这是基本的 Git worktree 核心概念，但在 Claude Code 中，它被包装成一个标志，因此你不必手动管理它。你可以从官方文档了解更多关于 Git worktree 的信息

3、入门：Claude --worktree 标志

Claude Code v2.1.50 引入了带有一个标志的原生 worktree 支持。以下是如何使用它。

在使用任何这些工作之前，请确保：

你的项目已经初始化了 git（git init）—— 让我们检查我们的仓库是否已初始化，使用这个：

git log --oneline

你在主分支上至少有一个提交

你在 Claude Code v2.1.50 或更高版本（运行 claude update 以检查）

3.1 启动 Worktree 会话

要在其自己的 worktree 中启动 Claude Code，添加 --worktree 标志（或简写 -w）：

claude --worktree

这会使用 Claude 选择的随机分支名称启动一个新的 worktree。它有效，但如果你一次运行多个 worktree，随机名称很快会变得混乱。

Claude Code 想出了这个名字：dreamy-puzzling-codd，你可以看到它创建了一个 worktrees 目录

更好的方法是为你的 worktree 命名：

claude --worktree feature/dark-mode

这会创建一个新的 worktree，签出一个名为 feature/dark-mode的分支，并在其中启动一个 Claude 会话 —— 全部在一个命令中！

3.2 你的 Worktree 位于哪里

Claude 在你的项目下将 worktree 存储在：

.claude/worktrees/feature-dark-mode/

你会在那里找到完整的、限定到该分支的工作文件集。你的主分支未受影响。

要确认当前激活了哪些 worktree，运行：

git worktree list

你会看到你的主 worktree 和每个链接的 worktree 以及它们的路径和分支名称。

3.3 导航到 Worktree 目录

如果你想直接从 worktree 的目录工作而不是从项目根目录，你有两个选项。

手动导航：

cd .claude/worktrees/feature-dark-mode

或者使用 --dir 标志在启动时，它会直接带你到那里：

claude --worktree feature/dark-mode --dir

3.4 恢复 Worktree 会话

我真的很喜欢的一件事 —— 如果你关闭一个会话并在稍后回来，你可以通过指定相同的名称从你离开的地方恢复：

claude --worktree feature/dark-mode

Claude 会为该 worktree 拾取会话。

你也可以按 Ctrl+W 在 Claude Code 内部查看项目中的所有会话并在它们之间跳转。

3.5 完成后清理

一旦功能被合并或你不再需要 worktree，删除它：

git worktree remove .claude/worktrees/feature-dark-mode

或者如果 worktree 有未跟踪的更改并且你想强制删除它：

git worktree remove --force .claude/worktrees/feature-dark-mode

请记住 —— 如果你创建了很多临时 worktree 而不清理它们，它们会在 .claude/worktrees/ 下堆积。养成合并后修剪的习惯。

git worktree prune

4、在并行 Git Worktree 中运行子代理

Worktree 不仅为单个 Claude 会话工作；子代理也支持它们。

与其让一个代理在同一分支上处理多个功能，你可以拥有专用子代理在各自的分支上同时工作，每个都在自己隔离的 worktree 中。

4.1 触发并行子代理

从你的主 Claude 会话，你可以指示 Claude 像这样通过 worktree 隔离启动子代理：

使用 worktree 为你的代理。并行构建 feature/dark-mode、
feature/local-storage 和 feature/edit-todos —— 
每个都在自己的分支上。确保每个代理在打开 PR 之前测试其更改 
结束。

Claude 将启动三个子代理，每个都在自己的 worktree 中，每个都在自己的分支上，全部同时运行。

当一个完成时，你可以独立合并或审查它，而不必等待其他的。

这是以前需要手动分支管理和多个终端会话的工作流。

4.2 使用 Worktree 隔离配置自定义代理

如果你在项目中定义了自定义子代理，你可以通过向代理的前面添加 isolation: worktree 来使 worktree 隔离自动化。

在 .claude/agents/your-agent.md 创建或编辑你的代理文件：

---
name: feature-builder
model: claude-sonnet-4-6
isolation: worktree
---
你是一个功能开发专家。当分配功能时，
完全构建它，编写测试并验证它工作后再完成。
始终在小的、集中的提交中工作。

使用 isolation: worktree 设置，每次调用此代理时，它自动获得自己的 worktree —— 不需要标志，不需要手动设置。Claude 处理它。

4.3 查看所有活动会话

当你有多个 worktree 运行时，在任何 Claude Code 会话中按 Ctrl+W 查看项目中每个活动会话。

这会给你一个快速概览，了解每个代理正在做什么，并让你在它们之间跳转。

4.4 使用桌面应用

如果你不想使用终端，Claude Desktop 应用也支持 worktree 模式。

前往代码选项卡，你会看到一个在开始会话之前可以启用的 worktree 复选框。

这是相同的功能，只是带有 GUI —— 如果你在终端和桌面应用之间上下文切换，这很有用。

5、非 Git 项目的 Worktree

如果你的项目使用 SVN 或 Mercurial，你仍然可以通过在 .claude/settings.json 中定义的钩子获得 worktree 风格的隔离：

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "jj workspace add \"$(cat /dev/stdin | jq -r '.name')\""
      }
    ],
    "WorktreeRemove": [
      {
        "command": "jj workspace forget \"$(cat /dev/stdin | jq -r '.worktree_path')\""
      }
    ]
  }
}

这告诉 Claude 在创建或删除 worktree 时运行你的版本控制的工作区命令。

6、结束语

Claude Code 的原生 Git Worktrees 是一个令人印象深刻的功能，适合正确的使用场景。

大型代码库迁移 — Boris Cherny（Claude Code 的创建者） 提到使用数百个并行代理进行大规模同步到异步迁移，每个代理处理一个文件夹并打开自己的 PR。
独立功能 — 当你的任务不共享文件或不依赖于彼此时，并行 worktree 消除了所有等待。
活动开发期间的错误修复 — 在一个 worktree 中修复生产错误，同时在另一个中继续构建，而没有任何分支污染。
代码审查 — 启动一个 worktree 来审查 PR，而不会干扰你当前的工作分支。

如果你一次构建多个活动功能，这值得今天添加到你的工作流中。

原文链接: I Tried (New) Claude Code Git Worktree (I Now Run Smooth Parallel Agents)

汇智网翻译整理，转载请标明出处