Git worktree trong Claude Code: các phiên song song

Thông tin thực tế về cách làm việc với Ailoot có trong tài liệu.

Git worktree trong Claude Code là gì#

Chạy nhiều agent song song trong cùng một thư mục là điểm đau cơ bản của vibe-coding với tốc độ năm 2026. Các AI agent viết mã nhanh hơn khả năng một người theo dõi xem ai đang động vào phần nào. Nếu không cô lập tệp, việc chạy hai phiên Claude Code song song trong cùng một thư mục sẽ kết thúc bằng việc phiên này ghi đè công việc của phiên kia.

Git worktree giải quyết vấn đề này ở cấp hệ thống tệp. Bạn có một thư mục chính để làm việc. Lệnh claude --worktree feature-auth tạo thư mục .claude/worktrees/feature-auth/ trên một branch riêng và khởi chạy Claude Code tại đó. Các tệp được cô lập. Thay đổi trong phiên này sẽ không hiển thị ở phiên kia cho đến khi bạn chủ động gộp chúng.

Tài liệu chính thức của Anthropic mô tả như sau:

Gợi ý tự kiểm tra: nếu bạn từng nhận được một commit mà một nửa số tệp là công việc của người khác, bạn cần worktree.

Git worktree khác branch thông thường như thế nào#

Quy trình Git tiêu chuẩn: bạn đang ở branch main và chạy git checkout feature-x — Git ghi đè các tệp của bản sao làm việc. Tiến trình npm run dev đang chạy bị hỏng vì package.json thay đổi ngay bên dưới nó. Bạn stash các thay đổi chưa commit và chờ IDE lập chỉ mục lại. Bạn chuyển về, mọi thứ lại bị ghi đè nên phải stash và pop một lần nữa.

Git worktree cho bạn một lựa chọn khác: thay vì chuyển đổi một thư mục giữa các branch, bạn tạo một thư mục thứ hai cho branch khác. Lệnh git worktree add ../project-feature-x feature-x tạo thư mục ../project-feature-x/ với các tệp từ branch feature-x. main vẫn ở thư mục ban đầu và máy chủ dev tiếp tục chạy.

Trước đây, chế độ worktree trong Claude Code phải được thiết lập thủ công: git worktree add, rồi cd, sau đó claude — và lặp lại trong từng terminal. Cờ --worktree (cũng là -w) thực hiện cả ba việc chỉ bằng một lệnh.

Khởi chạy phiên song song đầu tiên: cờ --worktree#

Ví dụ tối thiểu. Mở terminal đầu tiên tại thư mục gốc của dự án:

claude --worktree feature-auth

Claude Code thực hiện ba việc:

1. Tạo .claude/worktrees/feature-auth/ với snapshot của origin/HEAD (thường là branch mặc định của bạn).
2. Tạo branch mới worktree-feature-auth.
3. Khởi chạy phiên trong thư mục này.

Mở terminal thứ hai tại cùng thư mục gốc của repository:

claude --worktree bugfix-123

Xong. Hai phiên Claude Code, các tệp khác nhau trên ổ đĩa, các Git branch khác nhau. Nếu bạn viết phần xác thực ở phiên thứ nhất và sửa một bài kiểm thử thất bại ở phiên thứ hai, về mặt vật lý chúng không thể cản trở nhau.

Nếu không muốn nhập tên, Claude sẽ tự nghĩ ra một tên:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Mẹo cho người mới dùng Git: thêm .claude/worktrees/ vào .gitignore. Nếu không, khi chạy git status trong thư mục chính, bạn sẽ thấy nội dung của tất cả worktree dưới dạng tệp chưa được theo dõi:

# .gitignore
.claude/worktrees/

Một lỗi cần tránh: trước lần chạy --worktree đầu tiên trong thư mục mới, hãy vào thư mục đó bằng lệnh claude thông thường (không có cờ) và chấp nhận hộp thoại tin cậy workspace. Nếu không, cờ này sẽ thất bại với lỗi “trust not accepted” — kể cả khi kết hợp với -p để chạy ở chế độ headless.

Worktree nằm ở đâu và cách tìm chúng#

Vị trí mặc định được cố định: .claude/worktrees/<value>/ tại thư mục gốc của repository. Nếu dự án của bạn nằm trong ~/dev/my-app/, worktree feature-auth sẽ nằm ở ~/dev/my-app/.claude/worktrees/feature-auth/.

Với bố cục không tiêu chuẩn (ví dụ, nếu bạn muốn worktree nằm bên ngoài repository), có hook WorktreeCreate — sẽ nói thêm về hook này ở phần dưới, trong mục SVN và Mercurial.

Trong một phiên Claude, bạn có thể chuyển sang worktree hiện có khác. Chỉ cần nhắn trong cuộc trò chuyện: “switch to .claude/worktrees/bugfix-123”, Claude sẽ gọi công cụ EnterWorktree. Thư mục hiện tại vẫn nguyên vẹn — bạn có thể quay lại theo cách tương tự.

Lệnh Git tiêu chuẩn hiển thị danh sách tất cả worktree, bao gồm worktree chính và những worktree được tạo thủ công:

git worktree list

Kết quả sẽ trông như sau:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Sao chép .env và bí mật: tệp .worktreeinclude#

Khi --worktree tạo thư mục mới, nó chỉ nhận những gì đã được commit vào Git. .env chứa API key và .env.local chứa cấu hình cục bộ nằm trong .gitignore, nên không có trong worktree. Và lần chạy npm run dev đầu tiên thất bại với “MISSING DATABASE_URL.”

Giải pháp tự làm là sao chép .env thủ công sau mỗi lần chạy --worktree. Cách này hiệu quả một lần rồi bị quên. Giải pháp của Anthropic là tệp .worktreeinclude ở thư mục gốc dự án, liệt kê các tệp bị Git bỏ qua để tự động sao chép vào mọi worktree mới.

Tạo tệp .worktreeinclude ở thư mục gốc của repository:

.env
.env.local
config/secrets.json

Cú pháp giống .gitignore. Bạn có thể dùng các mẫu glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic đưa ra quy tắc rõ ràng để phòng tránh sự cố:

Nói cách khác, bạn không thể vô tình sao chép package.json thông qua .worktreeinclude — vì tệp này không nằm trong .gitignore. Bạn có thể thêm bất kỳ mẫu nào ở đó một cách an toàn.

Cùng một .worktreeinclude hoạt động trong ba chế độ: --worktree thủ công, worktree tự động cho subagent (xem bên dưới) và các phiên từ ứng dụng Claude dành cho máy tính để bàn.

Tạo worktree từ pull request để review mã#

Một tình huống review mã tiêu chuẩn: đồng nghiệp gửi PR; bạn cần kiểm tra mã, chạy kiểm thử và để lại bình luận. Với git checkout pull/1234/head thông thường, bạn lại chuyển đổi bản sao làm việc và làm hỏng phiên đang hoạt động.

Với cờ --worktree, chỉ cần một lệnh:

claude --worktree "#1234"

Điều gì xảy ra: Claude Code chạy git fetch origin pull/1234/head, tạo worktree tại .claude/worktrees/pr-1234/ và checkout branch của PR. Phiên bắt đầu. Bạn có thể yêu cầu ngay “read the diff, run the tests, and find logical errors” — trong lúc Claude làm việc, phiên chính của bạn trên main vẫn tiếp tục chạy.

Cú pháp thay thế là URL đầy đủ của pull request:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Ứng dụng trong dự án thực tế: kết hợp claude --worktree "#N" với subagent review mã của riêng bạn sẽ có được bản review tự động trong một hoặc hai phút. Khởi chạy nó ở chế độ nền, tiếp tục làm việc trong cửa sổ chính và quay lại xem kết quả qua claude agents.

Branch cơ sở: worktree.baseRef cho fresh hoặc head#

Thiết lập mặc định như sau: mọi worktree mới bắt đầu từ origin/HEAD. Ưu điểm là điểm bắt đầu sạch, được đảm bảo khớp với những gì CI sẽ thấy. Nhược điểm là nếu bạn có thay đổi chưa commit hoặc một số commit cục bộ vượt quá remote trên branch hiện tại thì chúng sẽ không được đưa vào worktree mới.

Để worktree bắt đầu từ commit HEAD cục bộ hiện tại, thêm vào .claude/settings.json hoặc settings toàn cục:

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

Giờ claude --worktree experimental-feature bắt đầu từ HEAD cục bộ. Hữu ích khi tính năng đã có commit local chưa push, không gồm sửa tracked còn chưa commit. Nếu tác nhân con cần chúng, giữ và chuyển rõ thay đổi cần, xem diff đích; đừng nhầm với .worktreeinclude xử lý tệp local bị ignore.

Thiết lập này chỉ chấp nhận chính xác hai giá trị: "fresh" (= origin/HEAD) và "head" (= local HEAD). Không hỗ trợ ref tùy ý như "feature-branch" hoặc hash commit — đây là hạn chế có chủ đích nhằm ngăn số lượng lựa chọn tăng theo cấp số tổ hợp.

Tự động cô lập subagent: isolation: worktree#

Khi bạn bảo Claude “launch three subagents: one reads the database, the second looks at the API, and the third checks the tests”, theo mặc định cả ba sẽ làm việc trong bản sao làm việc của bạn. Nếu dù chỉ hai agent cùng ghi vào một tệp tại một thời điểm, sẽ xảy ra xung đột. Giải pháp là tự động cấp cho mỗi agent worktree riêng.

Cách 1: yêu cầu bằng lời. Viết cho Claude trong cuộc trò chuyện:

Use worktrees for your agents.

Claude sẽ áp dụng cơ chế cô lập cho mọi subagent tiếp theo trong phiên này.

Cách 2: thiết lập rõ ràng ngay trong subagent. Trong tệp subagent (ví dụ .claude/agents/code-reviewer.md), thêm một trường vào frontmatter:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

Giờ đây mỗi lần khởi chạy subagent này đều có một worktree tạm thời trong .claude/worktrees/. Nếu subagent không ghi gì, thư mục sẽ tự động bị xóa khi nó kết thúc. Nếu có thay đổi chưa commit, Claude sẽ hỏi có giữ lại hay xóa chúng không.

Branch cơ sở cho worktree của subagent giống như với --worktree: theo mặc định là origin/HEAD; với worktree.baseRef: head là local HEAD.

Ma trận quyết định: worktree, /bg, subagent hay Agent View#

Các cách kết hợp thường gặp:

• “2 tính năng song song, thủ công” — hai terminal, mỗi terminal chạy claude --worktree. Trường hợp đơn giản nhất.
• “Khởi chạy refactor qua đêm; tôi sẽ đóng ứng dụng” — /bg + /goal với điều kiện hoàn tất. Phiên chạy độc lập với cửa sổ của bạn.
• “Một prompt, ba cuộc điều tra song song” — ba subagent với isolation: worktree. Mỗi agent ở trong sandbox riêng.
• “Hiện đang chạy những gì?” — claude agents. Bảng điều khiển của mọi phiên với các bộ lọc “running”, “blocked” và “done”.

5 lỗi thường gặp khi làm việc với worktree#

1. Đã khởi chạy worktree, thiếu .env, không thứ gì hoạt động. Đây là vấn đề thường gặp nhất. Worktree là một checkout mới không có các tệp bị Git bỏ qua. Giải pháp là thêm tệp .worktreeinclude chứa .env* và các cấu hình cục bộ cần thiết ngay khi thiết lập chế độ worktree. Kiểm tra để chắc chắn tệp nằm ở thư mục gốc của repository, không phải trong .claude/.

2. Bạn muốn chuyển sang branch chính, chạy cd về thư mục gốc và mất các thay đổi chưa commit trong worktree. Thư mục gốc và worktree là hai bản sao làm việc khác nhau. Bạn đã quay lại bằng cd; các thay đổi trong worktree vẫn ở nguyên đó — chúng không biến mất. Nhưng nếu bạn nhầm lẫn và chạy git stash trong thư mục chính vì nghĩ mình đang ở worktree, stash sẽ được tạo trên branch chính chứ không phải branch bạn mong muốn.

3. Đã khởi chạy 5 phiên song song và không nhớ mỗi phiên đang làm gì. Tài liệu Anthropic cảnh báo rõ rằng hầu hết nhà phát triển không thể xử lý về mặt nhận thức hơn 2–3 phiên. Dấu hiệu quá tải là mở Agent View mà không thể nói ngay mỗi agent đang làm gì. Hãy giới hạn ở hai phiên đồng thời. Nếu nhiệm vụ cần nhiều hơn, nên điều phối qua /goal + subagent thay vì làm thủ công.

4. Worktree từ -p (headless) không được tự động dọn dẹp. Lệnh claude --worktree feature-x -p "do thing" không hiển thị lời nhắc thoát tương tác, nên không có lúc Claude hỏi “remove the worktree?” Các worktree này sẽ tích tụ. Dọn thủ công bằng git worktree remove .claude/worktrees/feature-x. Hoặc dùng script cron để xóa mọi thứ cũ hơn 7 ngày.

5. Hộp thoại tin cậy trong thư mục mới. Nếu mở repository lần đầu và lập tức chạy claude --worktree, lệnh sẽ thất bại. Chạy claude không có cờ, chấp nhận tin cậy workspace rồi thoát — sau đó --worktree sẽ hoạt động. Đây là chủ ý để Claude không truy cập dự án của người khác khi chưa có sự đồng ý của người dùng.

Dọn dẹp: nội dung nào bị xóa tự động#

Logic dọn dẹp phụ thuộc vào những gì bạn đã làm trong worktree và cách bạn khởi chạy phiên. Tài liệu Anthropic liệt kê ba tình huống:

Tình huống 1: bạn vào, không làm gì rồi thoát — worktree bị xóa.

Tình huống 2: bạn làm một số việc nhưng không commit — khi bạn thoát, Claude sẽ hỏi “keep or remove?” “Keep” lưu thư mục và branch để dùng sau. “Remove” xóa thư mục cùng với các thay đổi chưa commit và commit mới. Đây là thao tác phá hủy dữ liệu — đừng bấm “remove” theo thói quen.

Tình huống 3: bạn khởi chạy với -p (headless), lệnh kết thúc rồi thoát. Worktree vẫn còn. Hãy dọn thủ công:

git worktree remove .claude/worktrees/feature-x

Ngoài ra, worktree từ subagent và phiên /bg được tự động xóa bởi quá trình dọn dẹp nền nếu chúng cũ hơn cleanupPeriodDays ngày (một thiết lập, thường mặc định là 30 ngày) và không có công việc chưa lưu. Quá trình dọn dẹp tự động không động đến worktree từ --worktree — đó là trách nhiệm của bạn.

Giải pháp thay thế cho SVN, Perforce và Mercurial: hook WorktreeCreate#

Nếu repository sử dụng Subversion hoặc Mercurial, cờ --worktree sẽ không hoạt động trực tiếp. Anthropic cung cấp một điểm mở rộng thông qua hai hook: WorktreeCreate (tạo bản sao cô lập) và WorktreeRemove (xóa bản sao đó).

Ví dụ hook SVN từ tài liệu chính thức:

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

Hook đọc tên worktree từ stdin ({ "name": "feature-auth" }), chạy svn checkout vào thư mục đã xác định trước và in đường dẫn ra stdout — Claude Code dùng đường dẫn đó làm thư mục làm việc cho phiên mới.

Lưu ý quan trọng: khi dùng hook riêng, .worktreeinclude không được sử dụng. Nếu cần .env hoặc các tệp khác bị Git bỏ qua trong thư mục mới, hãy sao chép chúng ngay trong script hook.

Tiếp theo: ba cơ chế song song có liên quan#

Worktree cung cấp khả năng cô lập tệp. /bg cung cấp khả năng cô lập context. Subagent cung cấp khả năng cô lập nhiệm vụ. Mỗi cơ chế tự giải quyết một vấn đề. Kết hợp lại, chúng cung cấp cách làm việc trên ba đến năm nhiệm vụ song song mà không bị quá tải nhận thức. Đây là bộ kỹ năng đằng sau vibe-coding nâng cao trong năm 2026.

Chủ đề này tự nhiên dẫn đến ba chủ đề liên quan: cách thiết lập agent tự động bằng /goal và Agent View, cách xây dựng subagent của riêng bạn cho các nhiệm vụ, và cách khởi chạy hàng trăm agent thông qua Dynamic Workflows.

Mở Ailoot.