Claude Code + Git Worktree - 并行运行多个 AI 代理

问题：一个 Claude Code、一个分支、一次一个任务

当你在某个仓库里运行 Claude Code，它会在当前检出的分支上工作。这听起来理所当然 —— 直到你意识到它意味着：

  • ❌ 每个仓库同一时刻只能跑一个 Claude Code 任务
  • ❌ 每个任务都会阻塞你做其他事
  • ❌ 如果 Claude 在任务中修改文件，你没法并行测试或评审另一个分支
  • ❌ 长耗时代理（5-20 分钟）意味着你有大量闲等时间

解决方案不是让自己更慢 —— 而是并行。而让 Claude Code 并行化的底层原语就是 git worktree。

本指南完整演示怎么把两者连起来 —— 包括手动配置，以及用 ParallelCode 的一键 UI。

为什么 git worktree 是 Claude Code 的正解

Git worktree 是附加到同一仓库的第二个（或第三个、第十个）工作目录，每个都在自己的分支上。它们共享对象数据库，成本极低。它们是磁盘上物理隔离的文件夹，一个 worktree 里的 Claude Code 无法触及另一个 worktree 的文件。

这同时带来三样东西：

  1. 隔离 —— 每个 Claude 实例只看到自己分支的文件
  2. 并行 —— N 个代理、N 个 worktree、N 个终端、N 个任务同时跑
  3. 安全 —— 一个 worktree 里的 Bug 任务无法损坏另一个 worktree

还不熟悉 worktree？先看 Git Worktree 完全指南。

手动配置：Claude Code + git worktree 完全纯命令版

先来看原生工作流，无任何工具辅助。你会发现这个原语本身多么简单。

第 1 步：为任务创建 Worktree

# 在主仓库里
cd ~/projects/myapp

# 为新功能创建 worktree
git worktree add ../myapp-feat-auth -b feat/auth origin/main

这会在 ~/projects/myapp-feat-auth/ 创建一个 worktree，位于 feat/auth 分支上。

第 2 步：在 Worktree 中启动 Claude Code

cd ../myapp-feat-auth
claude

Claude Code 以该 worktree 为当前目录启动。它看到的是 feat/auth，不是 main。任何文件编辑、任何 commit 都留在这个 worktree 里。

第 3 步：为并行任务重复

打开第二个终端：

cd ~/projects/myapp
git worktree add ../myapp-feat-search -b feat/search origin/main
cd ../myapp-feat-search
claude

现在你有两个 Claude Code 会话同时运行，在两个不同分支上，完全隔离。

再加第三个也行：

git worktree add ../myapp-fix-login -b fix/login-bug origin/main
cd ../myapp-fix-login
claude

第 4 步：合并成功的，丢弃失败的

当 Claude 完成任务：

# 在 worktree 里：评审改动
git diff main

# 满意的话：推分支
git push -u origin feat/auth

# 通过 PR 合并，或本地：
cd ~/projects/myapp
git merge feat/auth

# 清理 worktree
git worktree remove ../myapp-feat-auth
git branch -d feat/auth

如果 Claude 做错了，直接删掉 worktree 和分支 —— 对主工作零影响。

一个具体的 3 任务并行示例

假设你有个周五下午加三张工单：

  1. AUTH-42：新增"忘记密码"流程
  2. SEARCH-17：改进搜索排序
  3. BUG-203：修复时区显示 Bug

老方式（串行，约 4 小时）

15:00 — Claude 做 AUTH-42         [你等着]
15:45 — 评审 AUTH-42、commit、切回 main
15:55 — Claude 做 SEARCH-17       [你等着]
16:40 — 评审 SEARCH-17、commit
16:50 — Claude 做 BUG-203         [你等着]
17:20 — 评审 BUG-203、commit，收工

你有 2 小时 20 分钟在等。

Worktree 方式（并行，约 1 小时挂钟时间）

git worktree add ../myapp-auth-42   -b AUTH-42   origin/main
git worktree add ../myapp-search-17 -b SEARCH-17 origin/main
git worktree add ../myapp-bug-203   -b BUG-203   origin/main

三个终端、三个 claude 会话，都在 15:00 启动。到 15:50 三个都做完了，16:00-17:00 你评审三个 PR，而不是在闲等时间里敲键盘。

**每一批节省 2-3 小时。**一周做两次，相当于多出一整天。

没人提醒你的那些坑

Claude Code 在 worktree 里跑得很好 —— 但你要先熬过这些粗糙处。

1. node_modules 不共享

每个 worktree 是独立文件夹。Claude Code 会乐呵呵地在每个 worktree 里跑一次 pnpm install，3 个 worktree 里 3 份 node_modules = 3 倍磁盘占用。

修复： 用 pnpm（内容寻址仓库自动去重），或配共享缓存：

# 每个 worktree 的 .npmrc（或全局）
store-dir=~/.pnpm-store

Python 侧用 uv 的全局缓存解决同样问题。

2. 开发服务器抢端口

Claude 启了 pnpm dev 占 3000 端口。第二个 worktree 的 Claude 也想 3000 → 崩。

修复： 在 CLAUDE.md 或 slash command 里教 Claude 挑空闲端口，或给每个 worktree 设不同 PORT：

# 每个 worktree 里
echo "PORT=3001" > .env.local  # 每个 worktree 换个号

3. .env 文件不会复制

.env 本来就该 gitignore。新 worktree 没有密钥，Claude 跑不起来应用。

修复： git worktree add 之后复制：

cp ../myapp/.env ../myapp-feat-auth/.env
cp ../myapp/.env.local ../myapp-feat-auth/.env.local

或者写个小脚本包一下。

4. Hook 在错误目录里跑

.git/hooks/ 位于主仓库。某些 hook 使用 $GIT_DIR 时可能解析到主仓库而非 worktree。

修复： 在 hook 里用 git rev-parse --show-toplevel 找当前 worktree 根：

WORKTREE_ROOT="$(git rev-parse --show-toplevel)"
cd "$WORKTREE_ROOT"

5. Claude Code 的权限/白名单

Claude Code 从 .claude/settings.json 读项目级设置。每个 worktree 有自己的副本。如果希望所有 worktree 共享白名单，放到 ~/.claude/settings.json（用户级）。

6. 你会忘了哪个 worktree 是啥

并行一周之后你有 myapp、myapp-feat-auth、myapp-feat-search、myapp-fix-login、myapp-old-experiment，记不住哪个还活着。

修复： git worktree list —— 这是你最好的朋友。每天早上跑一次。

团队为什么从"手动 worktree"迁移到 ParallelCode

跑一周下来摩擦就显现了：

  • 创建 worktree = 3-4 条命令 + .env 复制 + 安装依赖
  • 启动 Claude = 再一条命令 + 等上下文加载
  • 清理 = worktree remove + 删分支 + 检查未提交
  • 状态总览 = git worktree list + 脑补每个分支在干嘛

这正是 ParallelCode 在 git worktree + Claude Code 之上构建的 UI：

手动流程ParallelCode
git worktree add ... && cd ... && cp .env && pnpm i && claude一次点击
脑子里记 worktree可视化看板
终端标签页泛滥单窗口内的标签式代理会话
手动清理归档/删除/合并按钮
仅 claude CLIClaude Code + Cursor Agent + 本地代理并列

完全可以用 shell 脚本自己搭 —— 但一旦你每天跑 3+ 个代理，点击式版本一周就值回成本。

免费下载 ParallelCode →

键盘党终极配置（给终端纯粹主义者）

如果你生活在 tmux/zellij 里，这是最接近 ParallelCode 工作流的无 GUI 方案。

1. 安装 worktree 快捷命令

加到你的 shell（.zshrc / .bashrc）：

wt() {
  local branch="$1"
  local repo_name="$(basename "$(git rev-parse --show-toplevel)")"
  local dir="../${repo_name}-${branch//\//-}"
  git worktree add "$dir" -b "$branch" origin/main
  cp .env "$dir/.env" 2>/dev/null
  cp .env.local "$dir/.env.local" 2>/dev/null
  cd "$dir"
  echo "✓ worktree 就绪：$dir"
}

现在 wt feat/auth 一条命令搞定全套配置。

2. tmux 布局里的 Claude Code

# 新 tmux 窗口，3 个面板，每个面板一个 worktree
tmux new-window -n parallel
tmux split-window -h && tmux split-window -v
tmux select-pane -t 0 && tmux send-keys "cd ../myapp-feat-auth && claude" C-m
tmux select-pane -t 1 && tmux send-keys "cd ../myapp-feat-search && claude" C-m
tmux select-pane -t 2 && tmux send-keys "cd ../myapp-bug-203 && claude" C-m

绑个快捷键就飞起。

3. 每周清理死 worktree

周五下午固定动作：

git worktree list | grep -v main
# 挑出过期的，然后：
git worktree remove ../myapp-old-experiment
git branch -D old-experiment

要避免的反模式

观察了几百个开发者上手这个工作流之后，常见错误：

❌ 一个 worktree 内部切分支 失去了意义。每个长任务 = 一个 worktree。

❌ 在主仓库的 main 上跑 Claude 一个失误 Claude 就提交到 main 了。永远用 worktree + 功能分支。

❌ 从不清理 一个月后 30 个 worktree，git worktree list 没法看。设个"周五清理"仪式。

❌ Claude Code 和你的编辑器共用同一个 worktree Claude 改文件，编辑器重载，你丢失未保存的改动。"你的工作"和"代理的工作"用不同 worktree。

❌ 两个代理共享一个 worktree Claude Code 和 Cursor Agent 同时写同一批文件 = 混乱。一个 worktree 一个代理。

Claude Code + Worktree FAQ

问：Claude Code 知道自己在 worktree 里吗？ 答：它看到的是一个正常的 Git 仓库。它能读 .git 元数据，会遵守当前分支。不需要特殊感知。

问：Claude Code 能自己创建 worktree 吗？ 答：可以 —— 在 .claude/settings.json 里允许 git worktree add，就能让 Claude 为自己开 worktree。有些用户用这个做"每任务一分支"的自主模式。

问：/resume 跨 worktree 工作吗？ 答：会话状态按目录存。在 myapp-feat-auth/ 启动的会话从该 worktree 恢复。移动 worktree 会破坏路径；别移动。

问：MCP 服务器在并行会话之间会冲突吗？ 答：大多数 MCP 服务器能处理并发连接。如果某个持有独占锁（如本地 SQLite），让它作为共享进程跑，别每个会话起一个。

问：密钥和 API key 怎么办？ 答：API key 放 ~/.claude/settings.json（用户级），每个 worktree 自动继承。项目特定工具放每个 worktree 的 .claude/settings.json。

问：Cursor Agent 也能这样吗？ 答：能 —— 同样的 worktree 模式适用于 Cursor Agent、Aider、Codex 或任何 CLI AI 工具。ParallelCode 支持在一个看板里混合使用。

继续阅读

别再一次只跑一个 Claude Code。

ParallelCode 把 git worktree + Claude Code + Cursor Agent 整合到一个看板里。创建 worktree、启动代理、切换任务 —— 全程不离开 UI。

免费、开源，兼容你现有的 Git 仓库。

下载 ParallelCode → · 快速入门 →