Tmux và Claude Code: Quản lý nhiều AI agent trong terminal và giới hạn của công cụ

Tmux và các AI agent lập trình đã trở thành một cặp bài trùng khó tách rời. Lý do rất đơn giản: agent là tiến trình chạy dài, cần bám lấy một terminal, còn tmux thì giữ được terminal đó sống sót qua mọi cú đóng cửa sổ hay rớt mạng. Bài viết dưới đây tổng hợp kinh nghiệm thực chiến khi dùng tmux để điều khiển Claude Code và nhiều agent song song.

Vì sao tmux hợp với AI agent đến vậy

Một AI agent lập trình là tiến trình chạy lâu, liên tục tương tác với terminal. Tmux khớp với đặc điểm này ở ba điểm:

• Sống sót qua mất kết nối: tmux server sở hữu pty chứ không phải cửa sổ terminal của bạn. Đóng cửa sổ, mất SSH, gập laptop — agent vẫn chạy và vẫn ở đó khi bạn quay lại.
• Nhiều phiên trong một cửa sổ: bốn agent thành bốn phiên có tên, chuyển đổi bằng một phím tắt thay vì săn lùng bốn cửa sổ trong app switcher.
• Scriptable từ bên ngoài: bất kỳ shell nào cũng có thể gõ vào agent đang chạy hoặc đọc màn hình của nó. Không cần tự xây IPC hay API — đây chính là lý do tmux liên tục xuất hiện trong các script điều phối agent.

Cờ có sẵn trước khi bạn tự viết gì

Claude Code đã tích hợp sẵn cơ chế này cho trường hợp một agent trên một nhánh. Hai cờ đáng chú ý:

• -w, --worktree [name]: tạo git worktree mới cho phiên làm việc
• --tmux: tạo phiên tmux cho worktree đó (bắt buộc phải đi kèm --worktree)

Như vậy toàn bộ thao tác "cô lập tác vụ này, cấp cho nó một phiên riêng" gói gọn trong một lệnh:

claude --worktree --tmux
# hoặc đặt tên cho worktree
claude --worktree auth-refactor --tmux

Có hai chi tiết cần lưu ý. Thứ nhất, --tmux sẽ báo lỗi nếu thiếu --worktree, tức đây là tính năng của worktree chứ không phải cờ tạo phiên tổng quát. Thứ hai, trên iTerm2 nó dùng pane gốc thay vì tmux thật — đẹp hơn nhưng các lệnh tmux trong phần còn lại sẽ không có gì để bám vào. Dùng --tmux=classic nếu bạn cần tmux thật bên dưới, đặc biệt khi định viết script.

Với một agent trên một nhánh, đây là câu trả lời đủ dùng. Nhưng nó không làm được những việc sau: chạy nhiều agent trong một phiên, bố trí pane để quan sát, gõ vào agent đang chạy từ script, báo cho bạn biết agent nào đang chờ, hay thiết lập trên máy remote qua SSH.

Mỗi dự án một phiên, đặt tên theo dự án

Nguyên tắc tổ chức giúp mọi thứ dễ thở: mỗi repo một phiên tmux, đặt tên theo repo. Không phải theo tác vụ, không phải theo agent — vì tác vụ đến rồi đi, còn dự án mới là thứ ổn định.

# khởi tạo phiên detached trong thư mục dự án
tmux new-session -d -s api -c ~/code/api

# attach vào phiên (tự tạo nếu chưa có)
tmux new-session -A -s api -c ~/code/api

Cờ -A là attach-or-create, cho phép chạy lệnh lặp lại an toàn. Rất tiện để đóng gói thành hàm shell trong ~/.zshrc. Lưu ý tên phiên không được chứa dấu . hoặc : vì tmux dùng chúng làm dấu phân cách target.

Khi đó tmux ls trở thành một bảng kiểm kê thực sự, và bạn có thể mở rộng bằng format string:

tmux list-sessions -F '#{session_name}  windows=#{session_windows}  attached=#{session_attached}'

Bố cục để quan sát nhiều agent

Bên trong một phiên, cấp cho mỗi agent một window riêng, đặt tên theo tác vụ. Window tốt hơn pane với những agent bạn không theo dõi trực tiếp, vì window không chiếm diện tích màn hình. Pane dành cho hai ba agent bạn muốn xem cạnh nhau ngay lúc này.

Một chi tiết rất dễ bỏ sót: khi tách pane phải chỉ định #{pane_current_path}. Nếu không, pane mới sẽ mở ở thư mục mà phiên khởi tạo, chứ không phải thư mục bạn đang đứng — và agent khởi chạy ở đó sẽ trỏ nhầm repo.

Bạn cũng có thể dùng main-vertical để có một pane lớn chứa agent đang điều khiển, phần còn lại xếp bên cạnh. Giá trị phần trăm cho main-pane-width cần tmux 3.2 trở lên; bản cũ hơn phải dùng số cột tuyệt đối.

Những dòng cấu hình .tmux.conf đáng có

Với một đội agent, vài thay đổi so với mặc định là gần như bắt buộc:

• history-limit 100000: agent sinh ra rất nhiều output, bạn sẽ cần cuộn ngược lại.
• default-terminal "tmux-256color" cùng terminal-overrides cho màu 24-bit, để TUI của agent hiển thị đúng thiết kế.
• allow-rename off: TUI của agent thích đổi tiêu đề terminal, không tắt thì window auth bạn đặt tên cẩn thận sẽ bị đổi thành thứ gì đó tùy hứng.
• escape-time 10: sửa lỗi "phím mũi tên bị trễ" bên trong agent — độ trễ mặc định khiến các TUI tương tác có cảm giác ì.
• monitor-activity on cùng visual-activity off: đánh dấu window có agent vừa sinh output trong lúc bạn đang ở chỗ khác.

Điều khiển agent bằng send-keys

send-keys gõ vào pane như thể bạn đang ngồi trước bàn phím. Đây là cách để lập trình agent từ cron, từ git hook, hoặc từ một agent khác. Nhưng có ba cái bẫy, xếp theo tần suất gặp:

Thứ nhất, tham số trần bị hiểu là tên phím. Enter, C-c, Escape là phím chứ không phải chữ. Nếu prompt của bạn chứa một trong những từ đó như một tham số riêng lẻ, nó sẽ bị gửi thành phím bấm. Dùng -l để gửi chuỗi nguyên văn.

Thứ hai, dấu chấm phẩy kết thúc lệnh tmux. Một dấu ; ở cuối đoạn text bị đọc thành dấu phân cách lệnh. Phải escape thành \;.

Thứ ba, TUI của agent cần một nhịp nghỉ giữa text và dòng mới. Nhiều ô nhập debounce hoặc render lại khi dán, khiến phím Enter đến cùng khung hình với text bị nuốt mất. Mẫu đáng tin cậy là gửi text, sleep 0.3, rồi mới gửi Enter. Ngắt một agent chạy loạn cũng dùng chính cơ chế này với C-c.

Đọc kết quả bằng capture-pane

capture-pane đổ nội dung pane ra stdout — nửa "đọc" của cặp đôi. Cờ -J quan trọng hơn vẻ ngoài của nó: không có nó, một dòng bị xuống hàng ở độ rộng terminal sẽ trả về thành hai dòng, và mọi lệnh grep bạn viết đều sai ở chỗ nối.

Nếu cần log liên tục thay vì ảnh chụp, pipe-pane sẽ stream toàn bộ output của pane ra một lệnh. Cờ -o là toggle, nên chạy hai lần là tắt. Output là dạng thô kèm escape sequence, cần lọc qua sed nếu muốn đọc lại sau này.

Giám sát trạng thái agent trên status line

Bất kỳ ai chạy vài agent trong tmux cũng sẽ sớm muốn có một status line cho biết agent nào đang làm việc, agent nào đang chờ mình. Cơ chế là #() trên status line — chạy một lệnh shell và nội suy kết quả, làm mới mỗi status-interval giây.

Cách làm phổ biến là capture từng pane rồi so khớp chuỗi để đoán trạng thái: gặp "Do you want" hay menu ❯ 1. thì là đang chờ duyệt; gặp "esc to interrupt" thì là đang chạy; còn lại là rảnh. Nó hoạt động và đáng để xây dựng, nhưng cần tỉnh táo về bản chất: đây là so khớp chuỗi trên khung hình TUI đã render, poll mỗi 5 giây, cho từng pane đang mở. Chuỗi so khớp phụ thuộc vào việc phiên bản agent in ra gì trong tuần này.

Một hướng nhẹ hơn dùng chính cơ chế theo dõi hoạt động của tmux: monitor-silence bắn cảnh báo khi pane không sinh output trong N giây — tín hiệu gần nhất với "agent đã dừng". Nhưng im lặng chỉ là proxy của hoàn thành, không phải báo cáo hoàn thành: một agent đang suy nghĩ rất lâu về một file lớn cũng im lặng y như vậy.

Detach, reattach và những gì sống sót

Bảng sống sót cần nhớ: đóng cửa sổ terminal, detach client, rớt SSH — agent vẫn chạy. Nhưng kill-session, kill-server, khởi động lại máy, hay tính năng "Reopen windows" của macOS — agent chết. Tmux server chỉ là một tiến trình thuộc user của bạn, không có gì giúp nó sống qua reboot, và scrollback của phiên mất khi server dừng.

Một chi tiết hay làm người dùng bối rối: pane của phiên detached được định cỡ theo client cuối cùng từng attach, hoặc 80x24 nếu chưa từng có ai. Agent render vào pane 80 cột trong lúc bạn đi vắng sẽ trông sai lệch khi bạn quay lại với màn 200 cột, cho đến khi nó vẽ lại.

Tmux qua SSH — nơi thực sự khó thay thế

Đây là địa hạt tmux gần như không có đối thủ. Chạy agent trên máy remote qua một đường truyền không đáng tin:

ssh devbox -t tmux new-session -A -s agents

Kết nối rớt giữa chừng, bạn chạy lại đúng lệnh đó và quay về đúng phiên đó với agent vẫn đang chạy. Nếu đường truyền tệ đến mức SSH liên tục chết, ghép thêm mosh.

Vấn đề tmux lồng nhau: nếu chạy tmux cả ở máy local lẫn máy remote, cả hai sẽ giành cùng một prefix. Cách xử lý là đổi prefix ở remote hoặc bấm prefix hai lần với bind C-b send-prefix.

Nơi tmux dừng lại

Tmux là phần mềm tốt. Nó giải quyết multiplexing và persistence gần như trọn vẹn, và đã làm việc đó từ năm 2007. Điều nó không làm là bất cứ thứ gì đặc thù cho agent — vì agent chưa tồn tại khi mô hình của nó được thiết kế.

• Không có khả năng nhìn ra agent nào đang chờ duyệt: agent chờ approval trông y hệt agent đang suy nghĩ, cũng y hệt agent đã xong từ hai mươi phút trước. Cả ba đều là "một pane có chữ".
• Không thông báo khi agent hoàn thành: monitor-silence là thứ gần nhất, và nó bắn với bất kỳ pane im lặng vì bất kỳ lý do gì. Tmux không có khái niệm "agent đã xong" vì nó không biết agent là gì.
• Scrape màn hình dễ vỡ về bản chất: capture-pane cho bạn khung hình đã render — spinner, ký tự vẽ khung, cột bị cắt, ANSI. Không phải điều agent đã nói, không phải tool nó gọi, không phải tool đó thành công hay thất bại. Mọi parser viết trên nền này sẽ hỏng khi agent cập nhật giao diện.
• Không có trạng thái chia sẻ giữa các phiên: hai agent ở hai phiên tmux không có cách nào thấy nhau. Muốn agent này đọc transcript của agent kia hay bàn giao công việc, bạn phải tự xây bằng file, lock và polling.
• Scrollback cho nhiều agent streaming rất tốn kém: history-limit 100000 nhân với hàng chục pane là bộ nhớ thật, giữ theo từng pane chừng nào server còn sống, và mất ngay khi nó dừng.

Không có điểm nào trong số này là khuyết điểm. Chúng là rìa của một công cụ được xây để multiplex shell cho một người ngồi trước bàn phím.

Với người dùng Việt Nam

Nếu bạn đang chạy Claude Code hay các coding agent khác trên VPS nước ngoài — tình huống khá phổ biến vì chi phí và độ ổn định đường truyền quốc tế — thì tmux qua SSH gần như là bắt buộc. Kết hợp với mosh sẽ giúp trải nghiệm bớt đứt gãy khi mạng trong nước chập chờn. Còn nếu bạn chỉ chạy agent trên máy cá nhân, cờ claude --worktree --tmux là điểm khởi đầu đủ tốt, hãy dùng nó trước khi tự tay viết script.

Điểm mấu chốt cần nhớ: giữ tmux cho máy remote, cho tiến trình chạy dài trên server, cho bất cứ đâu mà đường SSH là mắt xích mong manh. Nhưng khi thứ bạn đang quản lý là sáu agent, mỗi con đôi lúc cần bạn ra quyết định vào một thời điểm không đoán trước, thì vấn đề đã không còn là multiplexing nữa.