Workflow Antigravity multi-agent: 3 agent song song trên 1 VPS

Một trong những điểm mạnh của Antigravity là chạy nhiều agent song song qua Activity Feed. Tuy nhiên khi 3-4 agent cùng đụng vào 1 working directory, conflict file sẽ xảy ra: agent A đang edit auth.ts thì agent B move file đó đi, kết quả ai cũng fail. Giải pháp là git worktree, tách working tree mỗi agent.

Bài viết hướng dẫn setup pattern "3 agent 1 VPS" cụ thể: 1 dev VN dùng laptop + 1 Cloud VPS, vận hành 3 task song song không xung đột. Phù hợp dev làm freelance hoặc small team cần delivery nhanh nhiều feature mỗi sprint.

Yêu cầu: VPS 4 vCPU 8GB trở lên (3 agent + IDE remote tốn ~4-5GB RAM tổng), Antigravity đã setup Remote-SSH (xem bài hướng dẫn setup riêng), project đã clone trên VPS. Git phải bật worktree (git 2.5+, mọi distro mới đều OK).

Tại sao cần git worktree

Git worktree là tính năng cho phép check out nhiều branch cùng lúc vào nhiều thư mục riêng biệt, share chung repo metadata (.git). Trước worktree, dev phải clone repo nhiều lần hoặc git stash để switch branch, mất thời gian và disk.

Với multi-agent, worktree mang lại 2 lợi ích: (1) Mỗi agent có working tree riêng, edit file không ảnh hưởng agent khác. (2) Repo chỉ clone 1 lần (.git share), tiết kiệm 70-80% disk vs clone nhiều bản. Trên VPS dung lượng giới hạn, đây là yếu tố quan trọng.

Sơ đồ workflow 3 agent

Agent	Branch	Working tree	Task
Agent A (Backend)	feat/api-orders	~/projects/app-wt/api-orders	Thêm endpoint POST /orders
Agent B (Frontend)	feat/ui-cart	~/projects/app-wt/ui-cart	UI giỏ hàng React
Agent C (Test)	test/e2e-checkout	~/projects/app-wt/e2e-checkout	Playwright e2e checkout

Mỗi agent là 1 instance Antigravity Remote-SSH open vào folder worktree tương ứng. Cả 3 dùng chung VPS, chung .git repo, nhưng cô lập file working. Khi agent xong, git push branch lên Github/Gitlab, tạo PR.

Bước 1: setup repo và worktree

SSH vào VPS, clone repo chính một lần. Lưu ý tên folder dùng -bare để tránh confusion (hoặc giữ bình thường cũng OK):

cd ~/projects
git clone https://github.com/your-org/app.git app-main
cd app-main
git fetch --all

# Tạo 3 worktree cho 3 branch
git worktree add ../app-wt/api-orders feat/api-orders
git worktree add ../app-wt/ui-cart feat/ui-cart
git worktree add ../app-wt/e2e-checkout test/e2e-checkout

# List để kiểm tra
git worktree list

Mỗi worktree là 1 folder full source code (file thực, không phải symlink) nhưng .git là 1 file pointer trỏ về repo gốc. Disk usage chỉ tăng cho file mới, không duplicate .git history.

Bước 2: install dependency riêng cho từng worktree

Mỗi worktree cần node_modules riêng (vì branch có thể khác package.json). Chạy install song song:

cd ~/projects/app-wt/api-orders && npm install &
cd ~/projects/app-wt/ui-cart && npm install &
cd ~/projects/app-wt/e2e-checkout && npm install &
wait
echo "All installed"

Trick tiết kiệm disk: dùng pnpm với store chung. Cài pnpm bằng npm install -g pnpm, rồi pnpm config set store-dir ~/.pnpm-store. Mỗi worktree pnpm install sẽ link vào store chung thay vì duplicate, tiết kiệm 50-70% disk.

Bước 3: mở 3 cửa sổ Antigravity Remote-SSH

Trên laptop, mở Antigravity. F1 -> Remote-SSH: Connect to Host -> chọn VPS. Khi connected, File -> Open Folder -> chọn ~/projects/app-wt/api-orders. Đây là cửa sổ Agent A.

Mở thêm 2 cửa sổ Antigravity nữa (File -> New Window), mỗi cửa sổ Remote-SSH connect cùng VPS nhưng open folder khác: ui-cart và e2e-checkout. Antigravity reuse VS Code Server đã cài trên VPS, không cần install lại.

Trên taskbar bạn có 3 cửa sổ Antigravity, mỗi cửa sổ là 1 worktree. Switch qua lại bằng Alt+Tab. Mỗi cửa sổ có chat panel agent riêng, không share state.

Bước 4: giao task cho 3 agent

Trong cửa sổ 1 (api-orders), prompt:

Đọc file src/api/routes.ts. Thêm endpoint POST /orders
nhận body { items: Array<{product_id, qty}>, customer_id, address }.
Validate Zod, insert vào bảng orders với status='pending',
return 201 với order_id. Viết test unit cơ bản.

Switch cửa sổ 2 (ui-cart), prompt:

Tạo component CartPage.tsx hiển thị danh sách item,
mỗi item có qty stepper +/-, tổng tiền cuối trang.
Dùng Tailwind, state local useState. Mock data 5 item ban đầu.
Thêm button Checkout disable khi cart empty.

Switch cửa sổ 3 (e2e-checkout), prompt:

Viết Playwright test tests/e2e/checkout.spec.ts:
mở /cart, add 3 item, edit qty, click Checkout,
fill form address, submit, assert URL /thank-you
và message "Đơn hàng thành công" hiện ra. Mock backend
nếu chưa có endpoint thật.

3 agent chạy song song. Bạn ngồi xem hoặc làm task khác (review PR cũ, đọc docs). Mỗi 5-10 phút quay lại check Activity Feed, approve diff.

Bước 5: tránh xung đột khi merge

Mỗi worktree có branch riêng nên file không đụng nhau khi đang code. Vấn đề chỉ xảy ra khi merge cả 3 branch về main. Best practice:

• Trước khi giao task, chia rõ folder ownership: Agent A chỉ sửa src/api/, Agent B chỉ sửa src/components/, Agent C chỉ thêm vào tests/
• Nếu task cần edit file shared (vd types.ts), giao cho 1 agent (Agent A) làm trước, push branch, 2 agent còn lại rebase từ branch đó
• Tránh tất cả agent cùng đụng package.json (thêm dependency). Giao 1 agent cập nhật package, 2 agent còn lại pull về sau
• Lock file (package-lock.json, pnpm-lock.yaml) chỉ edit khi cần thiết, agent không tự sửa lock trừ khi cần

Bước 6: review và merge

Khi từng agent xong, dev commit trong từng cửa sổ (Antigravity show diff tổng, click Commit), push branch lên Github:

cd ~/projects/app-wt/api-orders
git add . && git commit -m "feat(api): add POST /orders endpoint"
git push origin feat/api-orders

# Tương tự cho ui-cart, e2e-checkout

Tạo 3 PR riêng trên Github. Có thể dùng tool gh CLI để tạo nhanh: gh pr create --fill. Reviewer (có thể là chính bạn hoặc team) merge từng PR khi đạt. Conflict thường ít vì đã chia ownership.

Tài nguyên VPS: tính toán RAM/CPU

Mỗi instance Antigravity Remote (qua VS Code Server) tốn ~300-500MB RAM trên VPS. Mỗi Node dev server (next dev, vite) ~400-800MB. Cộng cả 3 agent đang active:

Thành phần	RAM ước tính
VS Code Server (3 instance)	~1.5GB
Node dev server x 2 (Agent A, B)	~1.6GB
Playwright + Chromium (Agent C)	~600MB
OS + nginx + Postgres dev	~1.5GB
Cache, buffer, dự phòng	~1.5GB
Tổng	~6.7GB

VPS 4 vCPU 8GB là đủ. Nếu chạy 4-5 agent đồng thời, nâng lên 6-8 vCPU 16GB. CPU spike khi 3 agent cùng build sẽ saturate, nhưng vì agent thường idle chờ user prompt, throughput vẫn ổn.

Pattern nâng cao: hierarchical agent (1 leader + n worker)

Khi task phức tạp (vd refactor toàn module), pattern hierarchy hiệu quả: 1 agent leader (Ultra) đọc requirement, viết plan thành file plan.md trong worktree shared, sau đó 3 worker (Pro) đọc plan.md và execute từng phần.

Implement:

• Worktree shared: ~/projects/app-wt/leader (branch main hoặc planning)
• Worker 1, 2, 3 trên 3 branch riêng
• Leader edit plan.md, commit, push
• Worker pull plan.md từ main, đọc, thực thi phần của mình
• Khi worker xong, push branch, leader review tổng và merge

Pattern này giảm prompt overhead cho dev: chỉ tương tác với leader (cấp cao), worker tự đọc plan và làm. Phù hợp task >2 ngày work.

Tmux backup: agent chạy nền khi đóng laptop

Antigravity Remote disconnect khi laptop sleep, nhưng tmux session trên VPS giữ alive. Trước khi đóng laptop, mỗi worktree mở tmux pane riêng để chạy task long-running:

tmux new -s a-api
cd ~/projects/app-wt/api-orders && npm run build:all
# Ctrl+B D, mở session khác
tmux new -s a-ui
cd ~/projects/app-wt/ui-cart && npm run build
# Ctrl+B D

Sáng mở Antigravity Remote, mở terminal, tmux ls để xem session, tmux a -t a-api để attach và đọc log. Agent đã build xong, tiếp tục flow.

Cleanup worktree khi task xong

Khi branch đã merge, gỡ worktree để tránh tích luỹ:

cd ~/projects/app-main
git worktree remove ../app-wt/api-orders
git worktree remove ../app-wt/ui-cart
git worktree remove ../app-wt/e2e-checkout
git worktree prune

Branch local cũng nên xoá: git branch -d feat/api-orders. Folder worktree xoá tự động, không cần rm -rf thủ công.

Khi nào không nên multi-agent

3 agent song song không phải lúc nào cũng nhanh hơn 1 agent tuần tự. Một số case nên dùng đơn agent:

• Task phụ thuộc tuyến tính (cần A xong B mới làm được)
• Refactor toàn cục, 1 agent giữ context tốt hơn
• Dev mới làm quen Antigravity, switch context giữa 3 cửa sổ dễ rối
• VPS yếu (2 vCPU 4GB), chạy 3 agent sẽ thrash
• Project nhỏ chỉ có 1-2 file thay đổi mỗi sprint

FAQ

Có giới hạn số agent song song trong Antigravity không?

Antigravity client cho phép mở vô số cửa sổ (mỗi cửa sổ = 1 agent session). Giới hạn thực sự là quota API Gemini 3 (request/phút) và RAM/CPU VPS. Thực tế 3-5 agent là sweet spot.

Git worktree có conflict với node_modules không?

Không, node_modules nằm trong .gitignore nên không track. Mỗi worktree có node_modules riêng. Dùng pnpm với store chung để tiết kiệm disk.

Có thể dùng worktree với Docker container không?

Được, nhưng cần đảm bảo container của mỗi worktree dùng port khác nhau (vd 3001, 3002, 3003). Docker compose tách file riêng cho từng worktree hoặc override port qua env.

Agent có thể tự tạo worktree mới không?

Có, agent có thể chạy lệnh git worktree add trong terminal. Tuy nhiên việc tạo worktree thường là decision của dev, không nên để agent tự ý.

Nếu 2 agent vô tình edit cùng file, ai thắng?

Mỗi agent edit trong working tree riêng của nó, nên không thấy nhau. Conflict xảy ra khi merge branch trên Github. Lúc đó dev resolve thủ công hoặc nhờ agent thứ 4 (reviewer) phân xử.

Có quy tắc đặt tên worktree không?

Khuyến nghị đặt tên worktree theo branch (vd feat-api-orders), folder cha là app-wt/. Tránh tên chung chung như tmp, work. Tên rõ ràng giúp tmux session và cửa sổ Antigravity dễ phân biệt.