Worktrunk: git worktree cho nhiều AI agent song song

Bạn giao cho Claude Code sửa tính năng thanh toán, một agent khác sửa lỗi phân trang, một agent nữa viết test cho API. Nếu cả ba cùng làm việc trên một cây làm việc, kết cục quen thuộc là file bị ghi đè, branch bị đổi giữa chừng, và cuối ngày bạn ngồi gỡ xung đột thay vì review kết quả.

Git worktree sinh ra cho đúng điểm này: mỗi branch có một thư mục làm việc riêng. Nhưng lệnh git gốc cồng kềnh khi dùng hàng ngày. Worktrunk là CLI viết bằng Rust, bọc lên trên git worktree để rút gọn vòng đời đó thành vài lệnh ngắn.

Lưu ý: các lệnh dưới đây được đối chiếu với tài liệu chính thức, phiên bản v0.81.0 phát hành ngày 2026-10-20, kiểm chứng ngày 2026-10-31. Phần vận hành song song mình chưa chạy thử, chỉ đối chiếu tài liệu, nên hãy chạy thử một cặp worktree trước khi chuẩn hóa quy ước cho team.

Vấn đề thật: một repo, nhiều AI agent, xung đột file không tránh được

AI coding agent đọc file, sửa file và ghi kết quả trở lại cây làm việc. Khi hai agent cùng sửa một file, agent chạy sau có thể ghi đè thay đổi của agent chạy trước. Ngay cả khi hai agent sửa hai file khác nhau, việc đổi branch giữa chừng vẫn phá vỡ giả định của cả hai.

Cách tránh xung đột thủ công là clone repo thành nhiều bản, mỗi bản cho một agent. Cách này hoạt động, nhưng bạn phải tự đồng bộ branch và tự dọn dẹp khi xong.

Git worktree cho phép một repo có nhiều cây làm việc, mỗi cây gắn với một branch riêng, mà không cần clone lại toàn bộ lịch sử. Vấn đề nằm ở trải nghiệm: chuỗi tạo worktree, chuyển thư mục, khởi động agent, xóa worktree, xóa branch vừa dài vừa dễ quên một khâu.

Nhóm gặp vấn đề này rõ nhất là developer dùng Claude Code, Codex hoặc OpenCode hàng ngày và thường xuyên giao hai ba việc độc lập cùng lúc, cùng DevOps và maintainer cần review pull request mà không phá cây làm việc đang dở dang. Ngược lại, nếu bạn làm việc một mình, một task một lúc, git worktree gốc hoặc đổi branch liên tục đã đủ.

Worktrunk là gì và giải quyết đúng vấn đề nào

Worktrunk là CLI quản lý git worktree, được mô tả ngay từ đầu là dành cho workflow chạy nhiều AI agent song song. Dự án mã nguồn mở trên GitHub dưới tài khoản max-sixty, viết bằng Rust, tại thời điểm kiểm tra ngày 2026-10-31 có 9.565 stars cùng 342 forks. Bản v0.81.0 ra ngày 2026-10-20, chỉ khoảng ba tuần sau v0.80.0, nên đây vẫn là CLI còn trẻ và phát triển nhanh.

Điểm cần hiểu rõ ngay từ đầu: Worktrunk giải quyết xung đột ở tầng cây làm việc và branch, không giải quyết xung đột ở tầng trạng thái dùng chung. Ba agent chạy song song vẫn có thể giẫm chân nhau qua database dev dùng chung, Redis, cổng cố định, file .env hoặc migration. Theo mình, đây là điểm quyết định xem song song hóa có thực sự giúp bạn nhanh hơn hay chỉ dời xung đột từ Git sang runtime.

Worktrunk nằm ở một tầng khác với hai bài đã có trên blog này: cc-switch giải quyết việc chuyển đổi provider AI coding agent, còn superpowers là phương pháp làm việc với agent. Worktrunk là tầng cô lập workspace bên dưới cả hai.

Kiến trúc và cơ chế hoạt động

Worktrunk không chạy daemon hay server riêng. Nó là một binary CLI cộng với một shell function bọc ngoài, và phần bọc này là bắt buộc: một process con không thể đổi thư mục làm việc của shell cha, nên muốn wt switch đưa bạn sang thư mục khác, shell phải tự đổi thư mục sau khi binary trả về đích đến. Nếu bỏ qua bước cài đặt shell integration, bạn sẽ ở nguyên thư mục cũ.

Worktrunk có bốn nhóm chức năng: quản lý worktree và branch; bộ chọn tương tác kèm trạng thái CI; hooks và steps; và tích hợp agent qua cờ -x, cùng OpenCode, pi, omp và statusline của Claude Code.

Khi bạn gõ wt switch feat, Worktrunk phân giải tên đó thành branch hoặc pull request tương ứng, tạo worktree nếu cần, rồi chuyển shell sang thư mục đó. Với wt switch pr:123, đích đến là branch của pull request số 123.

Dạng lệnh đầy đủ cho workflow với agent là wt switch -c -x claude feat: -c tạo branch và worktree mới, -x claude khởi động Claude Code ngay trong worktree đó, phần sau dấu -- được truyền nguyên vẹn cho agent dưới dạng prompt:

wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'

Mỗi lệnh mở một worktree riêng, gắn một agent riêng, với một nhiệm vụ riêng. Vòng đời còn lại cũng gọn: wt list liệt kê worktree kèm trạng thái, wt remove dọn worktree và branch liên quan, wt merge main merge rồi dọn dẹp trong một lệnh.

Hai tính năng đáng chú ý là cổng dev-server riêng theo worktree và chia sẻ cache build. Bộ lọc hash_port sinh một cổng khác nhau cho mỗi worktree dựa trên tên branch. Lệnh wt step copy-ignored sao chép file bị gitignore, như cache build, từ worktree gốc sang worktree mới. Giới hạn quan trọng: cơ chế này dựa trên reflink nên chỉ hoạt động trên APFS, btrfs và XFS; trên ext4 và NTFS, mỗi worktree vẫn phải build lại.

Phụ thuộc duy nhất đáng kể của Worktrunk là Git và một shell tương thích. Worktrunk cũng không cô lập process, database, dịch vụ ngoài hay secret: mỗi worktree vẫn trỏ về cùng remote và vẫn đọc cùng một file .env nếu bạn copy nó sang.

Hướng dẫn triển khai từng bước

Bạn cần một repo Git đang hoạt động, Git đã cài đặt, một shell tương thích, và quyền ghi vào thư mục sẽ chứa các worktree. Hãy kiểm tra dung lượng đĩa trống trước: mỗi worktree là một checkout đầy đủ.

Với Homebrew, trên cả macOS và Linux:

brew install worktrunk && wt config shell install

Với Cargo: cargo install worktrunk && wt config shell install. Trên Arch: sudo pacman -S worktrunk && wt config shell install. Với conda-forge: conda install -c conda-forge worktrunk && wt config shell install.

Bước wt config shell install là bắt buộc: nó cài shell function cho phép wt switch đổi thư mục làm việc của shell hiện tại. Sau bước này, hãy mở lại shell hoặc nạp lại file cấu hình shell, rồi mới kiểm chứng.

Trên Windows, tên lệnh khác đi vì wt trùng với Windows Terminal:

winget install max-sixty.worktrunk
git-wt config shell install

Để kiểm chứng, chạy wt list trong một repo Git: kết quả mong đợi là danh sách các worktree hiện có kèm trạng thái, không có lỗi về shell integration. Tiếp theo, thử tạo một worktree thử nghiệm và kiểm tra rằng shell thực sự đổi thư mục:

wt switch -c thu-nghiem
pwd

Nếu pwd vẫn trỏ về thư mục cũ, shell integration chưa có hiệu lực: hãy chạy lại wt config shell install và nạp lại cấu hình shell. Khi đã đúng, xóa worktree thử nghiệm bằng wt remove.

Sau khi kiểm chứng, mẫu làm việc song song là ba lệnh ở mục kiến trúc, mỗi lệnh cho một feature, một agent và một prompt riêng sau dấu --. Nguyên tắc quan trọng: một agent, một worktree, một nhiệm vụ có biên rõ. Đừng giao cho hai agent cùng sửa một module, và đừng để hai agent cùng chạm vào một migration hay một bảng database dùng chung trong cùng một khung giờ. Trước khi dọn dẹp, luôn kiểm tra git status trong từng worktree, vì wt remove và wt merge có thể dọn cả branch và worktree.

Đánh giá: ưu điểm, nhược điểm và vận hành

Ưu điểm rõ nhất là giảm thao tác Git thủ công và giảm lỗi chuyển đổi thư mục. Vòng đời worktree gọn lại thành vài lệnh, agent được gắn vào đúng worktree ngay từ lúc tạo, và việc dọn dẹp sau merge không còn là danh sách kiểm tra dài mà bạn phải tự nhớ.

Nhược điểm cũng rõ ràng. Thứ nhất, bạn thêm một lớp trừu tượng lên trên Git: team phải học thêm quy ước đặt tên, vòng đời và cờ lệnh, và khi công cụ gặp lỗi lạ, bạn vẫn cần hiểu git worktree gốc để gỡ. Thứ hai, CLI còn trẻ, cờ lệnh và hành vi có thể thay đổi giữa các bản phát hành, nên tài liệu nội bộ cần ghi rõ phiên bản đã kiểm chứng. Thứ ba, Worktrunk không tự giải quyết xung đột ngữ nghĩa: hai feature song song có thể merge sạch về mặt Git nhưng vẫn mâu thuẫn về mặt logic, và không công cụ quản lý worktree nào thay thế được review và test trước khi đưa vào main.

Về bảo mật, cần nói thẳng: Worktrunk không sandbox agent và không cô lập secret. Mỗi worktree vẫn chia sẻ remote và, nếu bạn copy file cấu hình, vẫn chia sẻ cùng một bộ credential và cùng một database dev. Song song hóa vì vậy phải đi kèm kỷ luật tách tài nguyên ngoài: database riêng cho từng worktree, hoặc xếp lịch các task chạm trạng thái chung.

So sánh với các lựa chọn cùng phạm vi

So với git worktree gốc, Worktrunk dùng chung nền tảng và cho cùng một kết quả về mặt Git, khác biệt nằm ở tự động hóa và trải nghiệm. Git thuần không tốn thêm công cụ và ai cũng gỡ được bằng kiến thức Git sẵn có. Worktrunk đổi lại bằng tốc độ: một lệnh thay cho một chuỗi lệnh, agent gắn sẵn, bộ chọn có CI, merge kèm dọn dẹp. Nếu bạn chỉ thỉnh thoảng dùng worktree, Git thuần đã đủ; nếu bạn tạo và dọn worktree nhiều lần mỗi ngày cho agent, phần tiết kiệm sẽ cộng dồn nhanh.

So với clone nhiều bản repo, Worktrunk tiết kiệm thao tác đồng bộ vì mọi worktree vẫn thuộc cùng một repo. Tuy nhiên, về dung lượng checkout, Worktrunk không rẻ hơn clone: mỗi worktree vẫn là một cây làm việc đầy đủ.

So với đổi branch liên tục trên một cây làm việc, Worktrunk an toàn hơn hẳn cho agent song song vì không còn chuyện đổi branch giữa chừng phá vỡ giả định của agent khác. Cái giá là tài nguyên: nhiều thư mục, nhiều dung lượng đĩa, nhiều dev-server chạy cùng lúc. Với workflow một task một lúc, đổi branch vẫn là cách nhẹ nhất.

Kết luận so sánh, theo mình, khá thẳng: Git thuần đã đủ cho nhu cầu worktree không thường xuyên; Worktrunk đáng thêm vào toolchain khi bạn chạy agent song song thường xuyên và đã hiểu git worktree.

Trường hợp sử dụng thực tế

Trong workflow AI, mẫu rõ nhất là một agent sửa feature, một agent sửa bug, một agent viết test, mỗi agent một worktree. Ba task này độc lập ở tầng file, và nếu tài nguyên ngoài cũng được tách, chúng có thể chạy cùng lúc.

Trong doanh nghiệp, wt switch pr:123 cho phép review một pull request mà không phá cây làm việc đang dở dang. Với DevOps, worktree riêng là nơi thử nghiệm cấu hình, migration hoặc pipeline trước khi merge. Trên máy dev cá nhân và homelab, Worktrunk cho phép chạy song song các agent trên dự án self-host mà không cần nhiều máy.

Xử lý lỗi thường gặp

Lỗi phổ biến nhất là wt switch chạy nhưng shell không đổi thư mục, gần như luôn do thiếu shell integration. Cách xử lý là chạy lại wt config shell install, nạp lại cấu hình shell, rồi thử lại với một worktree thử nghiệm.

Lỗi thứ ba là wt step copy-ignored không giúp giảm thời gian build như kỳ vọng. Hãy kiểm tra hệ thống file: trên ext4 và NTFS, reflink không hoạt động nên lợi ích chia sẻ cache đơn giản là không có.

Lỗi thứ tư là worktree bẩn khi remove hoặc merge: thay đổi chưa commit hoặc branch còn commit chưa push. Cách xử lý là kiểm tra git status và git log, commit hoặc stash những gì cần giữ, rồi mới dọn dẹp.

Sao lưu và quay lại Git thuần

Rollback của Worktrunk rất sạch, vì nền tảng vẫn là git worktree và branch thuần. Gỡ Worktrunk không phá repo, và bạn có thể quay lại git worktree add, git worktree list và git worktree remove bất cứ lúc nào. Khi gỡ, hãy dọn shell integration khỏi file cấu hình shell và kiểm tra lại các worktree còn tồn tại.

Trước khi áp dụng cho một repo quan trọng, hãy đảm bảo mọi thay đổi quan trọng đã commit hoặc push, và thử quy trình tạo, merge, dọn dẹp trên một repo thử nghiệm trước.

Kết luận: ai nên dùng, ai nên dừng ở Git thuần

Worktrunk phù hợp với developer đã dùng Claude Code, Codex hoặc OpenCode song song thường xuyên, hiểu git worktree, và có các task đủ độc lập để tách thành từng worktree.

Worktrunk chưa phù hợp với người mới Git, với workflow một task một lúc, hoặc với môi trường không tách được database và dịch vụ dùng chung.

Bước tiếp theo, theo mình, nên đi theo thứ tự: cài đặt đúng theo hệ điều hành, bật shell integration và kiểm chứng rằng shell thực sự đổi thư mục, thử một cặp worktree song song với hai task độc lập, rồi mới chuẩn hóa hooks và quy ước merge cho team.

Tài liệu tham khảo

• Trang chủ và tài liệu chính thức của Worktrunk: https://worktrunk.dev
• Kho mã nguồn, README và các bản phát hành: https://github.com/max-sixty/worktrunk
• Tổng hợp các dự án GitHub nổi bật cuối tháng 10 năm 2026, trong đó Worktrunk được nhắc đến như công cụ quản lý nhiều agent trên một repo bằng git worktree: https://toolclove.com/blog/trending-github-projects-late-october-2026