Multi-Agent Claude Code với tmux: Chạy Song Song Nhiều AI Agents Cùng Lúc

Tại sao cần Multi-Agent Setup?

Một Claude Code instance hoạt động tốt cho single-file tasks. Nhưng với những project lớn hơn — migrate 20 components sang design system mới, refactor toàn bộ authentication layer, hoặc generate tests cho 50 functions — một agent sequential sẽ rất chậm.

Multi-agent setup với tmux cho phép chạy nhiều Claude Code instances song song: một orchestrator phân chia work, nhiều subagents thực thi độc lập, kết quả merge lại cuối cùng. Điều này biến công việc cần 2 giờ thành 30 phút.

Prerequisites

• Claude Code CLI installed
• tmux installed (brew install tmux trên Mac, apt install tmux trên Linux)
• iTerm2 (optional nhưng recommended cho UX tốt hơn)
• Git worktrees support (built-in với git 2.5+)

Khái niệm cơ bản: Orchestrator + Subagents

Orchestrator Agent

Instance chính nhận task lớn, phân tích, chia nhỏ thành subtasks, và assign cho các subagents. Orchestrator không code trực tiếp — nó coordinate.

Ví dụ prompt cho orchestrator:

"We need to migrate all 15 components in /src/components to use the new design system.
Split this into 15 parallel tasks and delegate to subagents.
Each subagent should work on one component independently.
After all complete, review for consistency."

Subagent Instances

Mỗi subagent nhận một subtask cụ thể và hoạt động hoàn toàn độc lập. Subagents không biết nhau tồn tại — chúng chỉ focus vào task của mình.

Setup tmux cho Multi-Agent Workflow

Cấu trúc tmux layout cơ bản

# Tạo new tmux session
tmux new-session -s claude-work

# Chia màn hình thành multiple panes
# Orchestrator ở pane trên
# Subagents ở các panes phía dưới

# Horizontal split
Ctrl+b, %    # vertical split (2 panes bên cạnh nhau)
Ctrl+b, "    # horizontal split (2 panes trên/dưới)

# Navigate between panes
Ctrl+b, arrow keys

Layout 1+3 (1 Orchestrator + 3 Subagents)

+------------------+
|   Orchestrator   |
+------+------+----+
| Sub1 | Sub2 |Sub3|
+------+------+----+

# Tạo layout này
tmux new-session -s claude-multi ;   split-window -v -p 40 ;   split-window -h ;   split-window -h ;   select-pane -t 0

Trick quan trọng: tmux -CC cho iTerm2

Nếu dùng iTerm2, flag -CC là game-changer:

tmux -CC new-session -s claude-work

Flag -CC (iTerm2 control mode) map tmux panes sang native iTerm2 tabs/windows thay vì render trong terminal. Kết quả:

• Native tab/window management của iTerm2
• Better scrollback, search, và copy/paste
• Cleaner UI so với managing hotkeys thủ công
• Nếu agents crash, iTerm2 là solid fallback

Git Worktrees: Isolation không Conflict

Multi-agent hoạt động tốt nhất khi mỗi agent làm việc trên branch/directory riêng. Git worktrees là giải pháp:

# Tạo worktrees cho mỗi feature
git worktree add ../project-auth feature/auth-migration
git worktree add ../project-ui feature/ui-components
git worktree add ../project-api feature/api-refactor

# Mỗi Claude Code instance mở trong worktree riêng
# Pane 1:
cd ../project-auth && claude

# Pane 2:
cd ../project-ui && claude

# Pane 3:
cd ../project-api && claude

Với worktrees:

• Mỗi agent có working directory riêng
• Không cần stash/unstash giữa tasks
• Không conflict khi multiple agents edit cùng lúc
• Dễ merge sau khi từng task hoàn thành

Workflow Thực Tế: Batch Component Migration

Scenario

Cần migrate 12 React components từ styled-components sang Tailwind CSS. Sequential: ~4 giờ. Parallel với 4 agents: ~1 giờ.

Bước 1: Setup 4 worktrees

for i in 1 2 3 4; do
  git worktree add ../project-batch-$i feature/tailwind-batch-$i
done

Bước 2: Mở tmux session với 4 panes

tmux new-session -s migration ;   split-window -h ;   split-window -v ;   select-pane -L ;   split-window -v

Bước 3: Launch Claude Code trong mỗi pane

Trong mỗi pane:

# Pane 1: components 1-3
cd ../project-batch-1 && claude
# Prompt: "Migrate Button.tsx, Input.tsx, Modal.tsx from styled-components to Tailwind"

# Pane 2: components 4-6
cd ../project-batch-2 && claude
# Prompt: "Migrate Card.tsx, Badge.tsx, Alert.tsx from styled-components to Tailwind"

# Pane 3: components 7-9
# ... etc

Bước 4: Review và merge

# Sau khi tất cả agents hoàn thành
for i in 1 2 3 4; do
  cd ../project-batch-$i
  git add .
  git commit -m "Migrate batch $i to Tailwind"
done

# Merge vào main
git worktree remove ../project-batch-1
# etc...

Orchestrator Pattern: Delegation từ Claude Code

Claude Code có khả năng built-in để spawn subagents. Bạn có thể describe workflow và let orchestrator handle delegation:

# Trong orchestrator pane, prompt:
"You are the orchestrator. The following 5 files need security review:
auth.js, user.js, payment.js, admin.js, api.js

Start 5 parallel subagent tasks, each reviewing one file.
Each subagent should: identify vulnerabilities, suggest fixes, output a report.
After all complete, synthesize findings into executive summary."

Claude sẽ tự spawn subagents (trong cùng instance hoặc yêu cầu bạn setup worktrees riêng tùy implementation).

Troubleshooting và Tips

Khi agents crash hoặc panes drop

tmux session persist kể cả khi terminal window đóng. Reconnect bằng:

tmux attach-session -t claude-work

Monitor progress

Trong orchestrator pane, thỉnh thoảng hỏi:

"Show me status of all running subtasks"

Context limit management

Với long-running agents, context có thể đầy. Dùng /compact trong subagent panes khi cần, hoặc setup checkpoint commits thường xuyên.

Resource limits

Nhiều agents song song = nhiều API calls = chi phí cao hơn. Plan accordingly. 3-5 agents parallel thường là sweet spot cho cá nhân; enterprise có thể scale lên nhiều hơn.

Xem thêm về multi-agent patterns tại Chief of Staff Agent — Điều phối multi-agent với Claude SDK, Agent Workflows — Chaining, Routing, Parallelization, và Claude Code toàn tập — Lập trình với AI agent trong terminal.

Advanced: Scripted Multi-Agent Workflows

Với workflows lặp lại thường xuyên, bạn có thể script toàn bộ setup:

#!/bin/bash
# multi-agent-setup.sh

PROJECT=$1
TASK=$2
NUM_AGENTS=${3:-3}

echo "Setting up $NUM_AGENTS agents for: $TASK"

# Create worktrees
for i in $(seq 1 $NUM_AGENTS); do
  git worktree add "../${PROJECT}-agent-$i" "feature/task-$i" 2>/dev/null || true
done

# Start tmux session with N+1 panes (1 orchestrator + N agents)
tmux new-session -d -s "${PROJECT}-multi"

# Create panes
for i in $(seq 1 $NUM_AGENTS); do
  tmux split-window -t "${PROJECT}-multi" -h
done

tmux select-layout -t "${PROJECT}-multi" tiled

# Launch Claude Code in each pane
tmux send-keys -t "${PROJECT}-multi:0.0" "cd $(pwd) && claude" Enter

for i in $(seq 1 $NUM_AGENTS); do
  tmux send-keys -t "${PROJECT}-multi:0.$i"     "cd ../${PROJECT}-agent-$i && claude" Enter
done

tmux attach-session -t "${PROJECT}-multi"

Sử dụng:

chmod +x multi-agent-setup.sh
./multi-agent-setup.sh my-project "migrate to TypeScript" 4

Cost Optimization

Multi-agent = nhiều API calls = chi phí tăng. Tips để optimize:

1. Size agents đúng

Không phải mọi subagent đều cần full context. Cho simple, repetitive tasks:

• Orchestrator: full context, expensive model
• Subagents cho simple refactoring: compact prompts, có thể dùng Haiku

2. Batch similar tasks

Thay vì 10 agents mỗi agent làm 1 file → 2-3 agents mỗi agent làm 3-5 files. Giảm overhead của context setup.

3. Checkpoint commits

Commit sau mỗi working state. Nếu agent đi sai hướng, revert và restart chỉ agent đó — không phải toàn bộ workflow.

4. Context hygiene

Dùng /compact trong subagents khi session dài. Compact conversation history giảm token consumption mà không mất key context.

Khi nào KHÔNG dùng Multi-Agent

Multi-agent không phải answer cho mọi vấn đề:

• Tasks có tight dependencies: Nếu file B phụ thuộc vào output của file A, phải sequential — parallel sẽ conflict
• Small tasks: Overhead setup tmux + worktrees lớn hơn benefit cho task chỉ cần 15 phút
• Tasks cần consistent style across all files: Parallel agents có thể diverge. Better: single agent với strong style guide
• Budget-sensitive situations: Multi-agent có thể 3-5x cost so với sequential

Real Benchmark: Migration Project

Case study từ community: migration 47 Python files từ Python 2 sang Python 3 syntax.

Sequential approach: Single Claude Code agent, ~4.5 giờ total

Multi-agent approach (5 agents, parallel): ~1.2 giờ total

Speedup: ~3.75x

Cost increase: ~2.8x (có overhead nhưng hiệu quả vì agents không phải idle)

Net result: 3.75x faster, 2.8x more expensive → worth it khi time-to-complete quan trọng hơn cost optimization.

Giám Sát và Debugging Multi-Agent Sessions

Logging Output Từ Mọi Agents

Khi nhiều agents chạy parallel, khó track progress thủ công. Setup logging:

# Redirect output của mỗi agent vào log file riêng
cd ../project-agent-1 && claude 2>&1 | tee ../logs/agent-1.log &
cd ../project-agent-2 && claude 2>&1 | tee ../logs/agent-2.log &

# Monitor tất cả logs đồng thời
tail -f ../logs/agent-*.log

Checkpoint Verification

Định kỳ check kết quả từ mỗi agent — đừng chờ đến cuối:

• Với migration tasks: sau mỗi 5 files, quick review sample output
• Với code generation: run tests sau mỗi major component
• Với content tasks: spot check 20% output trước khi continue

Xử lý Agent Failure

Khi một agent crash hoặc tạo output sai:

1. Identify scope của problem (chỉ file này hay broader?)
2. Revert changes: cd ../project-agent-X && git checkout .
3. Analyze lý do fail (insufficient context? ambiguous prompt?)
4. Fix prompt và restart chỉ agent đó — không interrupt others

Kết luận

tmux + Claude Code + Git Worktrees là combination mạnh mẽ cho developers cần xử lý large-scale refactoring hoặc batch tasks. Setup ban đầu mất 30 phút — nhưng khi đã có template, bạn có thể spin up multi-agent environment trong vài phút cho bất kỳ project nào.

Start với 2-3 agents trước, làm quen với workflow, sau đó scale lên khi comfortable. Đây là kỹ năng meta quan trọng cho kỹ sư muốn leverage Claude Code ở mức độ cao nhất.

Multi-agent setup không phải cho mọi task — nhưng với những project đủ lớn để justify overhead, productivity gain là real và measurable. Developer nào master workflow này sẽ có competitive advantage rõ ràng trong delivery speed và scope capacity.

Và nhớ: parallel is powerful, nhưng coordination là key. Orchestrator tốt = subagents hiệu quả. Spend time viết clear task specs cho mỗi agent — đây là investment xứng đáng.

Nguồn tham khảo

• Dariusz Parys — Claude Code Multi-Agent tmux Setup