Chạy phiên song song với worktree

Một git worktree là một thư mục làm việc riêng với file và nhánh riêng, nhưng chia sẻ chung lịch sử repository và remote với checkout chính. Chạy mỗi phiên Claude Code trong worktree riêng nghĩa là chỉnh sửa ở phiên này không bao giờ đụng file ở phiên khác - một phiên có thể xây tính năng trong khi phiên thứ hai sửa bug.

Ghi chú

Worktree yêu cầu git repository; với hệ quản lý phiên bản khác, cấu hình hook để thay thế logic git (xem VCS không phải git). Trong desktop app, mỗi phiên mới tự động có worktree riêng.

Worktree là một trong nhiều cách chạy Claude song song. Nó cách ly file, còn subagent và agent team điều phối bản thân công việc. Xem Chạy nhiều agent song song để so sánh các cách tiếp cận.

Hầu hết phiên chỉ cần hai mục đầu: khởi động Claude trong worktree, rồi dọn dẹp khi thoát.

Khởi động Claude trong worktree

Truyền --worktree hoặc -w kèm tên để tạo worktree cách ly và khởi động Claude trong đó. Mặc định worktree được tạo dưới .claude/worktrees/<tên>/ ở gốc repository, trên nhánh mới tên worktree-<tên>:

claude --worktree feature-auth

Chạy lệnh này lần nữa với tên khác ở terminal khác để mở phiên cách ly thứ hai. Bỏ qua tên, Claude tự sinh một tên như bright-running-fox.

Chạy tương tác yêu cầu workspace trust: nếu chưa từng chạy Claude trong thư mục đó, chạy claude một lần để chấp nhận dialog trust, hoặc --worktree sẽ thoát với lỗi nhắc bạn làm vậy. Chạy non-interactive với -p bỏ qua kiểm tra này.

Mẹo

Thêm .claude/worktrees/ vào .gitignore để nội dung worktree không hiện thành untracked file trong checkout chính.

Thiết lập môi trường cho worktree

Worktree là một checkout mới hoàn toàn, nên cần khởi tạo môi trường phát triển ở đó: nhờ Claude cài dependency, hoặc tự chạy setup của project trong thư mục worktree dưới .claude/worktrees/. Để copy tự động các file bị gitignore như .env vào mọi worktree mới, thêm file .worktreeinclude.

Nhờ Claude tạo worktree

Bạn cũng có thể yêu cầu Claude “work in a worktree” trong một phiên, nó sẽ tạo bằng tool EnterWorktree. Khi Claude vào một đường dẫn ngoài thư mục .claude/worktrees/ của repository, Claude Code sẽ hỏi bạn duyệt trước, vì việc chuyển này mang theo working directory, quyền ghi, và cấu hình project (CLAUDE.md, settings) của phiên đến vị trí mới.

Dọn dẹp worktree

Khi bạn thoát một phiên worktree tương tác, Claude kiểm tra worktree xem có công việc mà việc xoá sẽ làm mất không: file thay đổi/untracked, và commit mới.

• Worktree sạch: với phiên không đặt tên, Claude tự xoá worktree và nhánh của nó. Phiên đã đặt tên sẽ hỏi bạn trước để có thể giữ lại worktree cho sau này.
• Worktree còn công việc: Claude hỏi bạn muốn giữ hay xoá. Giữ thì thư mục và nhánh vẫn còn để quay lại sau; xoá thì mất cả worktree, nhánh, và mọi công việc trong đó.

Chạy non-interactive với -p không có prompt lúc thoát, nên Claude không dọn dẹp worktree của chúng - tự xoá bằng git worktree remove.

Resume một phiên worktree

Khi bạn resume một phiên từng nằm trong worktree, Claude Code đưa phiên trở lại đúng worktree đó - áp dụng cho resume tương tác, --continue/--resume ở non-interactive mode, và Agent SDK. Trong worktree, Claude vẫn có thể thoát ra bằng tool ExitWorktree.

Cách ly subagent bằng worktree

Subagent có thể chạy trong worktree riêng để các chỉnh sửa song song không xung đột. Yêu cầu Claude “use worktrees for your agents”, hoặc làm cố định cho một subagent tuỳ chỉnh bằng cách thêm isolation: worktree vào frontmatter.

Subagent này trong .claude/agents/ luôn chạy trong worktree riêng:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

Mỗi subagent nhận một worktree tạm, được Claude Code tự xoá khi subagent kết thúc mà không có thay đổi; worktree có thay đổi sẽ ở lại trên đĩa cho đến đợt quét dọn định kỳ.

Dọn dẹp worktree của subagent và background session

Một đợt quét định kỳ xoá các worktree Claude tạo cho subagent và background session sau khi chúng cũ hơn setting cleanupPeriodDays của bạn. Đợt quét bỏ qua worktree còn giữ công việc (file thay đổi/untracked, hoặc commit chưa push). Nó không bao giờ xoá worktree bạn tự tạo bằng --worktree.

Trong lúc agent đang chạy, Claude chạy git worktree lock trên worktree đó để dọn dẹp đồng thời không thể xoá nó.

Tuỳ chỉnh cách tạo worktree

Chọn nhánh gốc

Worktree mới mặc định nhánh từ nhánh mặc định của repository. Đặt worktree.baseRef trong settings để nhánh từ công việc hiện tại thay vào đó:

• "fresh" (mặc định): nhánh từ nhánh mặc định của repository trên remote.
• "head": nhánh từ HEAD local hiện tại của bạn, mang theo commit chưa push và trạng thái nhánh feature. Dùng khi cách ly subagent cần thao tác trên công việc đang dở.

{
  "worktree": {
    "baseRef": "head"
  }
}

Nhánh từ một pull request

Truyền --worktree kèm số PR (có #) hoặc URL PR đầy đủ. Claude Code fetch pull/<số>/head từ origin và tạo worktree tại .claude/worktrees/pr-<số>:

claude --worktree "#1234"

Copy file bị gitignore vào worktree

Worktree là checkout mới nên file untracked như .env từ repository chính không có sẵn. Thêm file .worktreeinclude ở gốc project (cú pháp .gitignore) để copy tự động - chỉ file khớp pattern và đang bị gitignore mới được copy:

.worktreeinclude

.env
.env.local
config/secrets.json

Dùng lại tên worktree

Truyền --worktree một tên đã tồn tại sẽ mở worktree đó thay vì tạo mới. Với base "fresh" mặc định, worktree mở lại sẽ reset về nhánh mặc định (thay vì tiếp tục ở tip cũ) nếu: không có thay đổi chưa commit/untracked, vẫn ở nhánh Claude Code tạo cho nó, và không có commit riêng (hoặc PR của nó đã merge và nhánh remote đã xoá).

Thay thế logic tạo worktree bằng hook

Cấu hình hook WorktreeCreate để thay thế hoàn toàn logic git worktree mặc định, kể cả đặt worktree ở nơi khác ngoài .claude/worktrees/.

Những gì worktree chia sẻ với checkout chính

Worktree có file và nhánh riêng, nhưng chia sẻ thư mục .git, plugin ở project scope, và permission approval đã lưu với checkout chính:

• Thư mục .git của repository: lệnh git trong worktree ghi vào thư mục .git dùng chung, sandboxing cho phép các ghi này.
• Plugin: plugin cài ở project scope từ checkout chính cũng load trong worktree của cùng repository.
• Permission approval: chọn “Yes, don’t ask again” cho một lệnh Bash trong phiên worktree lưu quy tắc vào .claude/settings.local.json của checkout chính, áp dụng cho checkout chính và mọi worktree khác của repository, và tồn tại kể cả khi worktree bị xoá.

Quản lý worktree thủ công

Tạo worktree trực tiếp bằng Git khi cần checkout một nhánh cụ thể đã tồn tại hoặc đặt worktree ngoài repository.

# Tạo worktree trên nhánh mới
git worktree add ../project-feature-a -b feature-a

# Tạo worktree từ nhánh đã tồn tại
git worktree add ../project-bugfix fix-issue-456

# Khởi động Claude trong worktree
cd ../project-feature-a
claude

# Liệt kê worktree
git worktree list

# Xoá khi xong việc
git worktree remove ../project-feature-a

VCS không phải git

Cơ chế cách ly bằng worktree mặc định dùng git. Với SVN, Perforce, Mercurial, hoặc hệ khác, cấu hình hook WorktreeCreate và WorktreeRemove để cung cấp logic tạo/dọn tuỳ chỉnh. Vì hook thay thế hành vi git mặc định, .worktreeinclude không được xử lý khi bạn dùng --worktree - copy file cấu hình local ngay trong script hook.

Ví dụ hook WorktreeCreate đọc tên worktree từ JSON qua jq, checkout một bản SVN mới, và in ra đường dẫn để Claude Code dùng làm working directory của phiên. Thêm vào settings.json:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

Kết hợp với hook WorktreeRemove để dọn dẹp khi phiên kết thúc.

Xem thêm

• Subagent: giao việc cho agent cách ly trong một phiên.
• Agent team: phối hợp nhiều phiên Claude tự động.

Nguồn

Dịch và biên soạn từ Run parallel sessions with worktrees.