worktree | Zachary

type

Post

status

Published

date

Mar 9, 2026

slug

tool_git

summary

Git Worktree + tmux 多 Agent 并行开发指南

一、核心概念与优势

什么是 Git Worktree？

git worktree 允许您在同一个 Git 仓库下创建多个独立的工作目录，每个目录可以检出不同的分支，但它们共享同一个 .git 对象库（历史记录、配置等）。

核心优势：

零拷贝，省空间：不需要克隆整个仓库，只复制工作区文件。

完全隔离：每个 Worktree 有独立的暂存区、未提交更改和依赖（如 node_modules、.env）。

无缝切换：无需反复 stash 或 checkout，多个任务可同时进行。

为什么结合 tmux 和 AI Agent？

当使用 Claude Code、Cursor 或其他 AI 编码助手时，Agent 需要持续的上下文和运行环境。如果在一个终端中频繁切换分支，Agent 的上下文会被破坏。

通过 tmux（终端复用器），我们可以为每个 Worktree 分配一个独立的 tmux Session 或 Window。这样，每个 Agent 都在自己的"平行宇宙"中运行，互不干扰，且可以随时挂起和恢复。

二、目录组织与架构设计

推荐结构：统一父目录模式

将主仓库和所有 Worktree 放在同一个父目录下，便于统一管理。

命名规范

使用清晰的前缀来标识 Worktree 的用途，避免混乱：

feature/* 或 feat-*：新功能开发

bugfix/* 或 fix-*：问题修复

ai/* 或 exp/*：AI 实验或重构任务

三、标准作业程序 (SOP)

完整工作流概览

步骤 1：创建 Worktree 与 tmux 会话

当有新任务（如开发新功能 feature-auth）时，不要在当前目录切换分支，而是创建一个新的 Worktree。

步骤 2：配置独立环境

由于 Worktree 是全新的目录，一些被 Git 忽略的文件（如 .env、node_modules）不会自动复制。

步骤 3：启动 AI Agent 与开发服务

在 tmux Session 中，利用 Pane（窗格）分割，同时运行 Agent 和开发服务。

Pane 1 (左侧)：运行开发服务器或测试监听

Pane 2 (右侧上)：启动 AI Agent（如 Claude Code）

Pane 3 (右侧下)：保留一个 Shell 用于手动执行 Git 命令或系统操作

tmux 快捷键：

Ctrl+b % - 垂直分割窗格

Ctrl+b " - 水平分割窗格

Ctrl+b ←/→/↑/↓ - 在窗格间导航

Ctrl+b d - 暂时挂起（Detach）当前 Session

步骤 4：并行处理多个任务

当紧急 Bug 出现时，无需打断当前的 AI Agent：

使用 Ctrl+b d 暂时挂起（Detach）当前的 tmux Session。

重复步骤 1-3，为 Bug 修复创建一个新的 Worktree 和 tmux Session。

在新的 Session 中启动另一个 AI Agent 处理 Bug。

步骤 5：完成与清理

任务完成后，合并代码并清理环境，防止磁盘和分支堆积。

⚠️ 重要：切勿直接 rm -rf 删除 Worktree 文件夹，这会导致 Git 内部状态混乱。始终使用 git worktree remove。

四、自动化工具推荐

手动执行上述步骤可能会繁琐。社区已经涌现出多个优秀的自动化脚本和工具，将 Git Worktree 和 tmux 完美结合。

工具名称	特点与优势	适用场景
workmux	一键创建 Worktree + tmux Window，支持配置文件 `.workmux.yaml` 自动执行 `pnpm install` 和复制 `.env`	追求极致自动化和配置化的开发者
muxtree	极简的 Bash 脚本，一条命令 `muxtree new feature-auth --run claude` 即可完成所有设置	喜欢轻量级、无依赖脚本的开发者
Claude Code 原生支持	Claude Code CLI 原生支持 `--worktree` 参数，自动在隔离环境中启动	深度依赖 Claude Code 的用户