↓ Chuyển đến nội dung chính

Claude Code AI Agents Git

Cách dùng worktree trong Claude Code: chạy nhiều agent song song mà không giẫm chân nhau

Cách dùng worktree trong Claude Code: lệnh claude -w, mang .env theo bằng .worktreeinclude, xử lý node_modules, base ref, dọn dẹp và chạy nhiều agent song song trong tmux.

Cách dùng worktree trong Claude Code: chạy nhiều agent song song mà không giẫm chân nhau

Muốn chạy Claude Code trong một git worktree, bạn chỉ cần khởi động bằng claude -w <tên> (dạng đầy đủ là --worktree). Claude Code sẽ tạo thư mục .claude/worktrees/<tên>/ ở gốc kho mã (repository), checkout vào đó một nhánh mới tên worktree-<tên>, tách ra từ nhánh mặc định trên remote. Từ lúc đó, phiên làm việc này chỉ được sửa file bên trong thư mục ấy. Mở terminal thứ hai, chạy lại đúng lệnh đó với một tên khác, là bạn có hai agent không thể đụng vào file của nhau. Cái bẫy nằm ở chỗ worktree là một bản checkout hoàn toàn mới: .env, node_modules và mọi thứ git bỏ qua sẽ không có ở đó cho tới khi bạn tự sao chép hoặc cài đặt. Gần như mọi rắc rối tôi từng gặp với worktree đều bắt nguồn từ đúng điểm này.

Tôi thường chạy nhiều agent song song, và tôi đến với worktree sau vài lần trả giá. Bài này nói về cách claude -w thực sự hoạt động (tôi kiểm tra trên phiên bản 2.1.328), .worktreeinclude dùng để làm gì, xử lý node_modules ra sao, tôi sắp xếp các phiên trong tmux thế nào, và khi nào tôi vẫn dùng git worktree add thuần.

Bài viết này dưới dạng video dài tám phút. Lời dẫn bằng tiếng Anh, có phụ đề tiếng Việt. Một số cảnh quay lấy từ Coverr.

Git worktree là gì, và vì sao một bản checkout không đủ cho nhiều agent
#

Git worktree là một thư mục làm việc riêng, có file và nhánh riêng, nhưng dùng chung lịch sử và remote với bản checkout chính. Nghe thì đơn giản, nhưng tôi chỉ thấy hết giá trị của nó sau khi chuyện xảy ra.

Một ngày tháng Chín, tôi để năm phiên Claude Code cùng làm việc trong một bản checkout duy nhất của ứng dụng marketplace tôi đang xây, và hai chuyện đã xảy ra. Một bản sửa một dòng trong file cấu hình kiểm thử đã sống sót qua bốn lần build thất bại, nhưng đến lúc commit thì biến mất: git commit báo working tree sạch, còn trong file là nội dung do một phiên khác viết. Kiểu cập nhật bị mất này không để lại dấu vết nào trong git: không có trong reflog, không có trong stash, thời gian sửa đổi cũng hoàn toàn bình thường. Cùng ngày hôm đó, một script triển khai (deploy) build thẳng từ working tree suýt đưa phần việc còn dang dở của một phiên khác lên production.

Sang tháng Mười thì có chuyện thứ ba. Một phiên commit file của mình ngay cạnh những thay đổi chưa stage của một phiên khác, và hook pre-commit đã stash toàn bộ những thay đổi chưa stage trong lúc hook chạy. Phần sửa của phiên kia biến khỏi ổ đĩa trong khoảng thời gian đó, trình kiểm tra kiểu (type checker) báo lỗi trên các file mới của nó, và lần commit bị huỷ. Thêm nữa, phiên nào cũng commit dưới tên tôi, nên nhìn git log cũng không biết ai đã làm gì.

Lý do dùng worktree gói gọn trong một câu: một working tree có nhiều người cùng ghi là một cuộc tranh chấp (race condition), và bên thua thậm chí không biết mình thua. Cho mỗi agent một working tree riêng là cuộc tranh chấp biến mất.

Một repository, ba thư mục làm việc. Lịch sử chỉ lưu một chỗ; file, HEAD và index thì mỗi worktree có riêng.

Cách dùng claude -w và cách nó hoạt động
#

Chạy thật trong một repository dùng xong là bỏ. Để ý cái khoá vẫn còn sau khi phiên đã kết thúc.

Dưới đây là những gì trang worktrees trong tài liệu chính thức viết, cộng với những gì tôi thấy khi tự chạy thử:

  • Vị trí và nhánh. claude -w add-search tạo .claude/worktrees/add-search/ trên nhánh mới worktree-add-search. Nếu bỏ trống tên, bạn sẽ nhận một tên tự sinh kiểu bright-running-fox. Nhớ thêm .claude/worktrees/ vào .gitignore, nếu không bản checkout chính sẽ hiện toàn bộ chỗ đó là file chưa được theo dõi (untracked).
  • Tách từ đâu (base ref). Mặc định worktree.baseRef là "fresh": tách từ nhánh mặc định trên remote, thường là origin/main. Nếu repository chưa fetch trong 24 giờ qua, Claude Code sẽ fetch trước, tối đa năm giây. Đặt thành "head" thì worktree mới tách từ HEAD hiện tại ở máy bạn, kèm cả những commit chưa push. Không thể đặt nó thành tên một nhánh cụ thể; muốn tạo từ một nhánh có sẵn thì tự dùng git worktree add.
  • Pull request. claude --worktree "#1234" sẽ fetch head của PR đó và tạo .claude/worktrees/pr-1234. Nhớ đặt trong dấu nháy, nếu không shell sẽ coi # là bắt đầu một chú thích.
  • Xác nhận tin cậy. Lần đầu chạy claude -w ở chế độ tương tác trong một thư mục chưa từng mở Claude, lệnh sẽ báo lỗi “Workspace trust not yet accepted”. Hãy chạy claude bình thường ở đó một lần và chấp nhận hộp thoại tin cậy. claude -p -w thì bỏ qua bước kiểm tra này.
  • Hàng rào. Khi phiên đang ở trong worktree, Claude Code từ chối sửa file trong bản checkout chính, từ chối lệnh có thư mục làm việc là bản checkout chính, và từ chối lệnh git trỏ ngược về đó qua git -C, --git-dir hay GIT_DIR. Tài liệu cũng nói rõ những gì nó không chặn: một lệnh cp hay chuyển hướng shell ghi vào bản checkout chính sẽ không bị các bước kiểm tra này từ chối.

Worktree dùng chung gì với bản checkout chính cũng quan trọng không kém những gì nó không dùng chung. Mọi worktree đều ghi vào cùng một .git, nên commit và nhánh tạo ở một worktree thì worktree nào cũng thấy. Plugin cấp dự án được nạp ở mọi nơi. Và một câu trả lời “Yes, and don’t ask again” trong worktree sẽ được lưu vào .claude/settings.local.json của bản checkout chính, nghĩa là phê duyệt đó áp dụng cho mọi worktree và vẫn còn sau khi worktree nơi bạn phê duyệt bị xoá. Tiện thật, nhưng cũng thêm một lý do để đừng bao giờ đưa bí mật (secret) vào những lệnh bạn phê duyệt.

Dọn dẹp, và cái khoá còn sót lại
#

Khi bạn thoát một phiên worktree ở chế độ tương tác, Claude Code kiểm tra xem xoá đi có mất gì không. Phiên không đặt tên mà worktree sạch thì bị xoá tự động, kể cả nhánh. Phiên có đặt tên thì sẽ hỏi trước. Nếu còn việc dang dở bên trong, bạn sẽ được hỏi có giữ lại không, và có thể quay lại sau bằng lệnh claude --worktree <tên> --resume mà nó in ra.

Chạy không tương tác thì khác, và đây là chỗ duy nhất làm tôi khựng lại khi thử. claude -p không có bước hỏi khi thoát, nên nó không dọn dẹp. Ngoài ra, Claude Code giữ một git worktree lock trên worktree trong lúc phiên chạy, và sau một lần chạy -p, cái khoá đó vẫn còn với một mã tiến trình (PID) không còn tồn tại. Bạn có thể thấy trong bản ghi ở trên: git worktree remove từ chối với thông báo “cannot remove a locked working tree, lock reason: claude session add-search”. Tài liệu mô tả đúng như vậy: một phiên sau đó sẽ dọn các khoá cũ, hoặc bạn chạy git worktree unlock trước. Biết rồi thì vô hại, nhưng lần đầu nhìn thấy cũng hơi giật mình.

.worktreeinclude: những file một bản checkout mới không có
#

Worktree chỉ chứa các file được git theo dõi. Muốn mang theo cả file bị git bỏ qua, hãy đặt một file .worktreeinclude ở gốc repository. File này dùng cú pháp của .gitignore, và Claude Code chỉ sao chép những file vừa khớp mẫu vừa bị git bỏ qua, nên file đã được theo dõi sẽ không bị sao chép trùng:

# .worktreeinclude
.env
.env.local
config/secrets.json

Nó áp dụng cho mọi worktree mà Claude Code tạo bằng git: claude -w, worktree của subagent và các phiên song song trong ứng dụng desktop. Nó không áp dụng cho worktree bạn tự tạo bằng git worktree add, và bị bỏ qua hoàn toàn nếu bạn thay quá trình tạo worktree bằng hook WorktreeCreate.

Tôi khuyên bạn đừng chỉ ghi mỗi .env, vì những file bị bỏ qua mà ta hay quên thường không báo lỗi ầm ĩ. Ứng dụng của tôi từng đổi script triển khai sang build từ một worktree sạch, để những sửa đổi chưa commit của các phiên khác không bao giờ lọt lên production. Nhưng working tree sạch đó lại thiếu các chứng chỉ ký (signing certificate) bị git bỏ qua mà một tính năng cần. Image vẫn build thành công, và tính năng đó lỗi trên production suốt 13 ngày, cho tới khi script được sửa để sao chép chứng chỉ vào và cảnh báo nếu thiếu cái nào. Một lần triển khai khác từ worktree thì thiếu một thư mục theme bị bỏ qua, và build chỉ thất bại sau khi một bước export mất hai phút đã làm bẩn working tree. Trước khi giao cho worktree bất cứ việc gì liên quan đến phát hành, hãy chạy git status --short --ignored trong bản checkout chính và xem trong đó có file nào mà quá trình build cần đọc.

node_modules: phần tốn kém nhất
#

.worktreeinclude dành cho file nhỏ. Nó không giúp được gì với node_modules, và Claude Code cũng không có cơ chế dùng chung nó giữa các worktree, nên worktree nào cần chạy code thì phải có node_modules riêng.

Git worktree thuần trong một repository demo: 84 KB cho đến khi cài đặt, rồi lại đủ 45 MB.

Với dự án thật, con số bắt đầu đáng ngại. Repository ứng dụng di động của tôi có 19 worktree bên cạnh bản checkout chính. Tôi đo 12 cái: từ 194 MB đến 12 GB, và bốn cái lớn nhất chính là bốn cái có node_modules riêng. Tuần này ổ đĩa laptop của tôi đã đầy 96%, nên nếu dọn thì nên bắt đầu từ chúng.

Các lựa chọn, từ đơn giản đến khéo léo:

  1. Cài riêng cho từng worktree. Bảo agent chạy npm install ngay từ đầu, hoặc tự làm. Chậm, tốn ổ đĩa, nhưng không bao giờ gây bất ngờ.
  2. Clone từ một bản checkout có cùng lockfile. Trên macOS, cp -c -R ../myapp/node_modules . dùng cơ chế clone của APFS, hai bên dùng chung khối dữ liệu cho tới khi một bên thay đổi. Clone 45 MB trong demo mất 0,8 giây. Tôi đã dùng cách này cho các lần triển khai thật từ worktree. Chỉ clone khi lockfile giống nhau, và cẩn thận với các thư mục build native: trong trường hợp của tôi, thư mục Pods của iOS trong bản checkout chính được build cho một SDK cũ hơn nhánh của worktree, nên phần đó phải cài lại từ đầu.
  3. Dùng pnpm. Các package nằm chung trong một store, và trên macOS pnpm thử clone trước rồi mới tới hard link (trên Linux và Windows thì hard link trước). Trong demo, lần cài cho worktree thứ hai mất khoảng năm giây.
  4. Cài trong hook WorktreeCreate. Hook này thay thế logic git mặc định của Claude Code, nên có thể chạy git worktree add rồi chạy luôn bước cài đặt. Cách này tôi chưa thử. Nếu bạn thử, nhớ rằng .worktreeinclude sẽ không còn được xử lý, và hook phải tự sao chép cả .env.

Chạy nhiều agent song song trong tmux
#

Tôi vốn đã sống trong tmux (bố cục nằm ở bài viết về cách tôi dùng Claude Code hằng ngày), nên worktree khớp vào ngay: mỗi worktree một cửa sổ, hoặc một pane. Dưới đây là ba agent được khởi động cùng lúc, mỗi agent được yêu cầu sửa cùng một file:

Ba agent, một file, không xung đột. Bản checkout chính vẫn sạch, mỗi thay đổi nằm chờ trên nhánh riêng.

Hai trong số đó sửa src/index.js cùng một lúc mà không hề biết đến nhau, vì src/index.js của mỗi agent là một file khác nhau trên ổ đĩa. Bản checkout chính vẫn sạch. Thứ còn lại ở cuối là ba nhánh cần review và merge, và đó là phần việc worktree không làm thay bạn được: nếu hai agent sửa cùng một dòng, bạn vẫn gặp xung đột khi merge. Chỉ khác là nó xuất hiện ở bước merge, nơi bạn nhìn thấy được, thay vì bị ghi đè trong im lặng.

Trong VS Code, worktree chỉ là một thư mục: code .claude/worktrees/add-search sẽ mở nó trong một cửa sổ riêng, trên nhánh riêng của nó.

Worktree là một bản chụp
#

Worktree cũng cũ đi. Ngày 19 tháng 11, một bản cập nhật OTA được phát hành từ một worktree đã chuẩn bị sẵn từ hai, ba ngày trước, và nó lặng lẽ hoàn tác hai bản sửa lỗi đã được phát hành từ chỗ khác trong khoảng thời gian đó. Lỗi được phát hiện và thay thế ngay trong ngày, nhưng chính sự cô lập hoàn hảo của worktree là vấn đề: nó chưa bao giờ nhìn thấy hai bản sửa ấy. Chỉ một dòng lệnh git là đã bắt được lỗi trước khi phát hành:

Phép kiểm tra nên chạy trước khi phát hành từ một worktree không phải vừa mới tạo.

baseRef: "fresh" giữ cho worktree mới luôn cập nhật. Không có gì giữ cho worktree cũ cập nhật cả, nên hãy kiểm tra trước khi phát hành từ chúng.

Subagent và hook
#

Bạn không cần mở một terminal cho mỗi agent để có được sự cô lập này. Một subagent tuỳ chỉnh có isolation: worktree trong front matter sẽ luôn chạy trong một worktree tạm của riêng nó:

---
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.

Đây là ví dụ lấy từ tài liệu. Worktree sẽ bị xoá nếu subagent kết thúc mà không thay đổi gì; worktree có thay đổi thì được giữ lại cho tới khi đợt dọn dẹp định kỳ có thể xoá mà không làm mất việc. Một chi tiết nhỏ: subagent chạy trong worktree nằm dưới .claude/worktrees/ nhận chỉ dẫn từ cuộc hội thoại chính, và không nạp file CLAUDE.md ở gốc worktree.

Hook WorktreeCreate và WorktreeRemove thay thế hoàn toàn logic git. Chúng dành cho các hệ thống quản lý phiên bản khác, hoặc khi bạn muốn đặt worktree ở chỗ khác ngoài .claude/worktrees/, nhưng cũng là nơi hợp lý cho các bước chuẩn bị như cài đặt ở trên.

Khi nào git worktree add thuần lại tốt hơn
#

Thú thật, thư mục .claude/worktrees trong repository ứng dụng của tôi đang trống. Cả 19 worktree đều được tạo bằng git worktree add thuần, tất cả trong một tháng qua, và một nửa đang ở trạng thái detached HEAD. Các repository khác trên laptop còn có thêm 40, 40, 18, 10, 3, 2 và 2 cái nữa. Mà phần lớn không phải do tôi tạo: trong 638 bản ghi hội thoại Claude Code trên chiếc laptop này, có 85 bản ghi mà agent chạy git worktree add, tổng cộng 336 lần.

Git thuần tốt hơn khi:

  • Bạn cần một nhánh cụ thể đã có sẵn, ví dụ nhánh release giữ lại để vá nóng (hotfix). baseRef không làm được việc này.
  • Bạn chỉ muốn phát hành đúng một bản sửa. Các phiên khác đã commit lên main những phần việc chưa được triển khai, nên tôi tạo một worktree detached tại đúng commit đang chạy trên production, cherry-pick riêng bản sửa của mình vào đó và triển khai từ đó. Nhờ vậy, thứ được phát hành chỉ có bản sửa ấy.
  • Bạn tự viết chỉ dẫn cho agent. Khi khởi động nhiều agent trên một repository, trong chỉ dẫn cho mỗi agent tôi đều ghi: tạo worktree riêng bằng git worktree add --detach "$TMPDIR/<task>-wt" refs/remotes/origin/main, push bằng git push origin HEAD:main, và rebase khi có xung đột.
  • Bạn muốn giữ nó lại. Đợt dọn dẹp của Claude Code không bao giờ xoá worktree mà bạn tự tạo bằng git worktree add.

claude -w tốt hơn khi bạn tự tay mở một phiên và muốn nó lo hết việc tạo nhánh, sao chép .env, dựng hàng rào quanh bản checkout chính và dọn dẹp. Dùng lẫn cả hai cũng không sao: tạo bằng cách nào thì Claude Code cũng coi đó là worktree, và những thứ dùng chung với bản checkout chính như đã nói ở trên vẫn y nguyên.

Tóm tắt
#

Mỗi phiên chạy song song dùng một claude -w <tên>, và thêm .claude/worktrees/ vào .gitignore. Trong .worktreeinclude, đừng chỉ ghi .env, hãy liệt kê mọi file bị bỏ qua mà quá trình build cần. Tính trước chuyện node_modules: cài riêng từng worktree, clone, hay dùng pnpm. Sau một lần chạy -p, có thể còn lại một cái khoá cần git worktree unlock. Trước khi phát hành từ một worktree không phải vừa tạo, hãy kiểm tra nó đã có những gì đang chạy trên production chưa. Worktree ngăn các agent ghi đè file của nhau, nhưng không ngăn chúng bất đồng ý kiến, nên cuối cùng người ngồi review ba nhánh vẫn là bạn.

Đọc thêm
#

Trên blog này:

Nguồn khác: