parallel-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Parallel Worktrees

并行Worktree

Run multiple AI coding sessions in parallel — each isolated in its own git worktree, pushing to its own branch, opening its own PR.

并行运行多个AI编码会话——每个会话都独立在自己的git worktree中，推送到专属分支，创建专属PR。

When to Use This Skill

适用场景

Activate when:

User wants to run two or more AI agents on different features/bugs at once
User asks about
```
git worktree
```
for agent sessions
User wants parallel PRs from a single repo without multiple clones
User needs to set up, coordinate, or clean up concurrent agent workspaces

在以下场景激活此技能：

用户希望同时在不同功能/Bug上运行两个及以上AI Agent
用户询问针对Agent会话使用
```
git worktree
```
的方法
用户希望从单个仓库创建并行PR，无需多次克隆
用户需要设置、协调或清理并发的Agent工作区

Decision Tree

决策流程

What does the user need?

Start a new parallel session?
  → Create a worktree + branch (Lifecycle §1–2)
  → Open a terminal/agent session pointed at the worktree path
  → Brief the agent: "Work only in <worktree-path>. Branch: <branch-name>."

Push and open a PR?
  → git push -u origin <branch>
  → gh pr create (GitHub PR Sync reference)
  → Note related PRs in the description

Sync a worktree with the latest main?
  → Inside the worktree: git fetch origin && git rebase origin/main
  → Never merge across worktrees directly

Merge and clean up?
  → Merge PR on GitHub
  → git worktree remove <path> && git branch -d <branch>
  → git worktree prune

Hit an error?
  → "already checked out" → branch open elsewhere; use a new branch name
  → ".git/index.lock" → two processes on same worktree; one agent per worktree
  → Detached HEAD → git switch -c <new-branch> inside the worktree
  → Stale entry after dir deleted → git worktree prune

用户需要什么？

启动新的并行会话？
  → 创建worktree + 分支（生命周期§1–2）
  → 打开指向worktree路径的终端/Agent会话
  → 告知Agent：“仅在<worktree-path>中工作。分支：<branch-name>。”

推送并创建PR？
  → git push -u origin <branch>
  → gh pr create（参考GitHub PR同步文档）
  → 在描述中注明关联PR

将worktree与最新main分支同步？
  → 在worktree内执行：git fetch origin && git rebase origin/main
  → 切勿直接跨worktree合并

合并并清理？
  → 在GitHub上合并PR
  → git worktree remove <path> && git branch -d <branch>
  → git worktree prune

遇到错误？
  → "already checked out" → 分支已在其他位置检出；使用新的分支名称
  → ".git/index.lock" → 同一worktree存在两个进程；每个worktree仅分配一个Agent
  → Detached HEAD → 在worktree内执行git switch -c <new-branch>
  → 目录删除后出现 stale 条目 → git worktree prune

Core Concepts

核心概念

Worktree vs clone — A worktree shares the same

.git

directory as the main checkout. No double-fetch, no disk waste. Each worktree checks out a different branch. Isolated at the filesystem level; same object store.

One agent, one worktree, one branch — This is the cardinal rule. Two agents sharing a worktree will corrupt each other's index. Two agents on the same branch will produce conflicting history.

PRs as the coordination channel — Agents communicate intent through PR titles, descriptions, and comments — not through shared files or direct worktree reads.

Worktree与克隆的区别 —— Worktree与主checkout共享同一个

.git

目录，无需重复拉取，不浪费磁盘空间。每个worktree对应一个不同的分支，在文件系统层面隔离，但共享对象存储。

一个Agent对应一个worktree和一个分支 —— 这是核心规则。两个Agent共享同一个worktree会破坏索引，两个Agent使用同一个分支会产生冲突历史。

PR作为协作通道 —— Agent通过PR标题、描述和注释传达意图，而非通过共享文件或直接读取worktree。

Layout Convention

目录布局规范

Keep worktrees as siblings of the repo root to avoid

.gitignore

noise:

~/projects/
  myrepo/              ← main checkout (main branch)
  myrepo-wt/           ← worktree root (sibling dir)
    feat/auth/         ← worktree for branch feat/auth
    fix/login-bug/     ← worktree for branch fix/login-bug

将worktree作为仓库根目录的同级目录，避免

.gitignore

产生冗余内容：

~/projects/
  myrepo/              ← 主checkout（main分支）
  myrepo-wt/           ← worktree根目录（同级目录）
    feat/auth/         ← 对应feat/auth分支的worktree
    fix/login-bug/     ← 对应fix/login-bug分支的worktree

Lifecycle

生命周期

1. Create a worktree

1. 创建worktree

bash

undefined

bash

undefined

New branch (most common)

新分支（最常用）

git worktree add ../myrepo-wt/feat/auth -b feat/auth

From an existing remote branch

基于已有远程分支

git worktree add ../myrepo-wt/fix/login-bug origin/fix/login-bug

undefined

git worktree add ../myrepo-wt/fix/login-bug origin/fix/login-bug

undefined

2. Brief the agent

2. 告知Agent

Give the agent its workspace clearly:

Working directory: /home/user/projects/myrepo-wt/feat/auth
Branch: feat/auth
Scope: implement JWT authentication — do not touch files outside this scope

The agent operates entirely within this directory. It should have no awareness of other worktrees.

明确告知Agent其工作空间：

工作目录：/home/user/projects/myrepo-wt/feat/auth
分支：feat/auth
范围：实现JWT认证——请勿修改此范围外的文件

Agent将完全在此目录内操作，无需知晓其他worktree的存在。

3. Work and commit

3. 开发与提交

Normal git flow inside the worktree — the agent uses

git add

git commit

as usual. The branch is isolated from main and all sibling worktrees.

在worktree内遵循常规git流程——Agent正常使用

git add

、

git commit

。该分支与main分支及其他同级worktree完全隔离。

4. Push and open PR

4. 推送并创建PR

bash

git push -u origin feat/auth
gh pr create \
  --title "feat(auth): implement JWT login" \
  --body "Parallel session. Related: #<pr-number> (if any)."

See

references/github-pr-sync.md

for draft PRs, PR templates, and linking.

bash

git push -u origin feat/auth
gh pr create \
  --title "feat(auth): implement JWT login" \
  --body "并行会话。关联PR：#<pr-number>（如有）。"

如需了解草稿PR、PR模板及关联方法，请查看

references/github-pr-sync.md

。

5. Sync with main

5. 与main分支同步

bash

undefined

bash

undefined

Inside the worktree

在worktree内执行

git fetch origin git rebase origin/main # keep history linear


Run this before opening a PR and before the final merge.

git fetch origin git rebase origin/main # 保持历史线性


请在创建PR前和最终合并前执行此操作。

6. Merge and clean up

6. 合并与清理

After the PR merges on GitHub:

bash

undefined

在GitHub上合并PR后：

bash

undefined

From the main repo (not inside the worktree)

在主仓库执行（不要在worktree内）

git worktree remove ../myrepo-wt/feat/auth git branch -d feat/auth git worktree prune # removes stale metadata entries

undefined

git worktree remove ../myrepo-wt/feat/auth git branch -d feat/auth git worktree prune # 移除陈旧的元数据条目

undefined

Branch Naming

分支命名规范

Use a consistent pattern so agents (and humans) can parse ownership at a glance:

<type>/<scope>/<short-description>

feat/auth/jwt-login
fix/api/null-pointer
chore/deps/upgrade-pnpm
agent/experiment/refactor-parser   ← for exploratory agent sessions

使用统一的命名模式，方便Agent和人员快速识别分支用途：

<类型>/<范围>/<简短描述>

feat/auth/jwt-login
fix/api/null-pointer
chore/deps/upgrade-pnpm
agent/experiment/refactor-parser   ← 用于Agent探索性会话

Pitfalls

常见问题

Symptom	Cause	Fix
`fatal: 'branch' is already checked out`	Branch open in another worktree	Use a new branch name
`.git/index.lock` errors	Two processes on same worktree	One agent per worktree
Detached HEAD	Created from a commit SHA, not a branch	`git switch -c <new-branch>`
Worktree path gone after reboot	Dir deleted externally	`git worktree prune` , then recreate
`git worktree list` shows stale entries	Dir removed without `git worktree remove`	`git worktree prune`
Agent edits files in main checkout	Agent not scoped to worktree path	Re-brief agent with explicit working directory

症状	原因	修复方案
`fatal: 'branch' is already checked out`	分支已在其他worktree中检出	使用新的分支名称
`.git/index.lock` 错误	同一worktree存在两个进程	每个worktree仅分配一个Agent
Detached HEAD	基于提交SHA创建，而非分支	执行 `git switch -c <new-branch>`
重启后worktree路径消失	目录被外部删除	执行 `git worktree prune` 后重新创建
`git worktree list` 显示陈旧条目	删除目录时未使用 `git worktree remove`	执行 `git worktree prune`
Agent修改主checkout中的文件	未限制Agent的worktree路径	重新告知Agent明确的工作目录

References

参考文档

Read these when you need more depth:

```
references/worktree-lifecycle.md
```
— Full command reference, flags, edge cases (multiple worktrees, bare repos, moving worktrees)
```
references/github-pr-sync.md
```
— PR creation, draft PRs, linking, status checks, merge strategies via
```
gh
```
CLI
```
references/agent-coordination.md
```
— Patterns for coordinating output across parallel sessions: sequencing, handoffs, shared state via PRs

如需深入了解，请阅读以下文档：

```
references/worktree-lifecycle.md
```
—— 完整命令参考、参数、边缘场景（多worktree、裸仓库、移动worktree）
```
references/github-pr-sync.md
```
—— 通过
```
gh
```
CLI创建PR、草稿PR、关联PR、状态检查、合并策略
```
references/agent-coordination.md
```
—— 跨并行会话协调输出的模式：排序、交接、通过PR共享状态

Setup & Activation

安装与激活

bash

npx skills add -g onsager-ai/dev-skills --skill parallel-worktrees -a claude-code -y

Auto-activates when: user mentions "worktree", "parallel agents", "multiple agent sessions", or asks to work on several features simultaneously with AI.

bash

npx skills add -g onsager-ai/dev-skills --skill parallel-worktrees -a claude-code -y

自动激活场景：用户提及“worktree”、“parallel agents”、“multiple agent sessions”，或请求同时使用AI开发多个功能时。