Chạy nhiều agent Claude Code song song với git worktree + tmux + ai-devkit

$BASE/                        # thư mục cha
├── myapp/                    # worktree main   → agent tên "main"
├── myapp-glossary/           # worktree feature → agent tên "glossary"
├── myapp-blog/               # worktree feature → agent tên "blog"
└── myapp-api/                # (repo khác cũng để đây được, miễn không là worktree)

brew install tmux git
npm i -g ai-devkit
# Claude Code — native installer (khuyến nghị)
curl -fsSL https://claude.ai/install.sh | bash

sudo apt update && sudo apt install -y tmux git curl
# Node.js: khuyến nghị nvm để tránh bản nodejs quá cũ trong apt
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec "$SHELL" -l
nvm install --lts

npm i -g ai-devkit
curl -fsSL https://claude.ai/install.sh | bash

tmux -V          # ≥ 3.0 là ổn
git --version    # ≥ 2.20 (cần worktree --porcelain)
node -v          # ≥ 18
claude --version
ai-devkit --version

export BASE="$HOME/projects/myapp-workspace"
cd "$BASE/myapp"

# Tạo worktree + branch mới cùng lúc
git worktree add -b feat/glossary "$BASE/myapp-glossary" origin/main
git worktree add -b docs/blog     "$BASE/myapp-blog"     origin/main

# Kiểm tra
git worktree list

/home/you/projects/myapp-workspace/myapp            97f6a49 [main]
/home/you/projects/myapp-workspace/myapp-glossary   97f6a49 [feat/glossary]
/home/you/projects/myapp-workspace/myapp-blog       97f6a49 [docs/blog]

#!/usr/bin/env bash
# agents.sh — quản lý agent Claude theo git worktree (mỗi agent = 1 tmux session)
# Viết theo cú pháp bash 3.2 → chạy được cả macOS (bash cũ) lẫn Ubuntu (bash 5).
#
# Nguyên lý:
#   - Context của Claude gắn với CWD (worktree), KHÔNG gắn với tên agent.
#     `claude --continue` nối lại phiên mới nhất của worktree đó
#     -> kill agent rồi tạo lại (cùng worktree) = làm tiếp việc cũ.
#   - ai-devkit TỰ discover các phiên claude này, nên `ai-devkit agent list/console/send`
#     vẫn quản lý được dù ta bật qua tmux.
#   - Danh sách agent tự suy ra từ `git worktree list` -> thêm worktree không cần sửa script.
#
# Dùng — TẠO agent (thao tác tmux thuần, KHÔNG lag):
#   agents up            # mở lại các agent feature còn thiếu (bỏ qua main)
#   agents new <name>    # tạo/tái tạo 1 agent theo tên (tự --continue)
#   agents open <name>   # attach/nhảy vào 1 agent
#   agents ls            # trạng thái các agent (tmux + ai-devkit)
#   agents kill <name>   # kill 1 agent
#   agents kill-all      # kill tất cả (hỏi xác nhận)
#   agents sync          # rebase origin/main cho mọi worktree
#
# Dùng — DỰ PHÒNG khi ai-devkit console lag (qua CLI, không cần TUI):
#   agents send <name> "lời nhắn"   # gửi tin cho agent (ai-devkit agent send)
#   agents detail <name>            # xem 20 dòng cuối của agent
#   agents console                  # session 'console' riêng (console+shell chia đôi, né lag)

set -euo pipefail

# ─────────── SỬA 4 DÒNG NÀY CHO PROJECT CỦA BẠN ───────────
# Tên project = tên thư mục của worktree main, cũng là tiền tố của các worktree khác.
PROJECT="${AGENTS_PROJECT:-myapp}"
# Thư mục cha chứa TẤT CẢ worktree (main + feature).
BASE="${AGENTS_BASE:-$HOME/projects/$PROJECT-workspace}"
# Worktree main — nơi chạy các lệnh git chung.
MAIN="${AGENTS_MAIN:-$BASE/$PROJECT}"
# Model ép cho mọi agent lúc phóng. Đổi tạm: AGENTS_MODEL=claude-fable-5 agents up
AGENT_MODEL="${AGENTS_MODEL:-claude-opus-5}"
# ───────────────────────────────────────────────────────────

# Tiền tố tên tmux session. Để rỗng nếu chỉ chạy 1 project trên máy;
# đặt "$PROJECT-" nếu chạy nhiều project (mọi project dùng CHUNG một tmux socket).
SESSION_PREFIX="${AGENTS_SESSION_PREFIX:-}"

# Socket tmux riêng (tuỳ chọn). Rỗng = dùng socket mặc định của tmux.
# Đặt tên -> mọi lệnh tmux trong script tự chèn `-L <tên>`: cách ly CỨNG, `kill-all`
# của project này không thể chạm session của project khác. Xem mục 15.6.
TMUX_SOCKET="${AGENTS_TMUX_SOCKET:-}"

# Bọc tmux để khỏi rải cờ -L ở từng lệnh. `command tmux` gọi binary thật nên không
# đệ quy. Hàm phải nằm TRONG script này: hàm khai báo ở shell của bạn không truyền
# sang tiến trình con, đặt trong alias sẽ vô tác dụng (mục 15.6).
tmux() {
  if [ -n "$TMUX_SOCKET" ]; then
    command tmux -L "$TMUX_SOCKET" "$@"
  else
    command tmux "$@"
  fi
}

# Lệnh phóng trong mỗi session. Override để test: AGENTS_CMD='sleep 999'
# --model ép model ngay lúc phóng (default toàn cục KHÔNG áp cho phiên --continue).
CLAUDE_CONT="${AGENTS_CMD:-claude --continue --model $AGENT_MODEL || claude --model $AGENT_MODEL}"

CONSOLE_SESSION="${SESSION_PREFIX}console"

NAMES=()
PATHS=()

# Tên tmux thật sự của một agent (có tiền tố nếu bạn bật SESSION_PREFIX).
tmux_name() { printf '%s%s\n' "$SESSION_PREFIX" "$1"; }

# Suy ra tên agent + đường dẫn từ `git worktree list`.
#   myapp-glossary -> glossary ; myapp-blog -> blog ; myapp (main) -> main
load_agents() {
  NAMES=(); PATHS=()
  local path="" name=""
  # Mỗi entry: dòng "worktree <path>" ... kết thúc bằng một dòng trống.
  while IFS= read -r line; do
    if [ "${line#worktree }" != "$line" ]; then
      path="${line#worktree }"
    elif [ -z "$line" ] && [ -n "$path" ]; then
      name="$(basename "$path")"
      name="${name#$PROJECT-}"
      [ "$name" = "$PROJECT" ] && name="main"
      NAMES+=("$name"); PATHS+=("$path")
      path=""
    fi
  done < <(git -C "$MAIN" worktree list --porcelain)
  # flush entry cuối nếu output không kết bằng dòng trống
  if [ -n "$path" ]; then
    name="$(basename "$path")"; name="${name#$PROJECT-}"
    [ "$name" = "$PROJECT" ] && name="main"
    NAMES+=("$name"); PATHS+=("$path")
  fi
}

path_for() {
  local want="$1" i=0
  while [ $i -lt ${#NAMES[@]} ]; do
    [ "${NAMES[$i]}" = "$want" ] && { printf '%s\n' "${PATHS[$i]}"; return 0; }
    i=$((i+1))
  done
  return 1
}

alive() { tmux has-session -t "$(tmux_name "$1")" 2>/dev/null; }

start_one() {   # tạo nếu chưa có
  local name="$1" path
  if ! path="$(path_for "$name")"; then
    echo "  ✗ không có worktree tên '$name' (xem: agents ls)"; return 1
  fi
  if alive "$name"; then echo "  • $name — đang chạy, bỏ qua"; return 0; fi
  tmux new-session -d -s "$(tmux_name "$name")" -c "$path" "$CLAUDE_CONT"
  echo "  + $name -> $path"
}

cmd_up() {   # bỏ qua 'main' (nơi chạy console/integrator, không cần agent riêng)
  local i=0
  echo "Mở lại agent còn thiếu (bỏ qua 'main'):"
  while [ $i -lt ${#NAMES[@]} ]; do
    if [ "${NAMES[$i]}" = "main" ]; then i=$((i+1)); continue; fi
    start_one "${NAMES[$i]}"
    i=$((i+1))
  done
  echo
  echo "Xong. \`agents ls\` để xem; \`agents open <name>\` để vào."
  echo "(Muốn bật agent cho main: \`agents new main\`)"
}

cmd_new() {     # tái tạo 1 agent (kill session cũ, bật lại --continue)
  local name="${1:?dùng: agents new <name>}"
  path_for "$name" >/dev/null || { echo "✗ không có worktree tên '$name'"; return 1; }
  tmux kill-session -t "$(tmux_name "$name")" 2>/dev/null || true
  start_one "$name"
}

cmd_open() {
  local name="${1:?dùng: agents open <name>}" t
  t="$(tmux_name "$name")"
  alive "$name" || { echo "✗ '$name' chưa chạy — \`agents new $name\`"; return 1; }
  if [ -n "${TMUX:-}" ]; then tmux switch-client -t "$t"; else tmux attach -t "$t"; fi
}

cmd_ls() {
  echo "=== worktree / agent ==="
  local i=0
  while [ $i -lt ${#NAMES[@]} ]; do
    local n="${NAMES[$i]}" st="ngủ"
    alive "$n" && st="chạy"
    printf "  %-12s %-5s %s\n" "$n" "$st" "${PATHS[$i]}"
    i=$((i+1))
  done
  echo
  echo "=== ai-devkit discover ==="
  ai-devkit agent list 2>/dev/null || echo "  (ai-devkit không sẵn sàng)"
}

cmd_sync() {    # đồng bộ với main. Conflict -> DỪNG, không tự resolve.
  git -C "$MAIN" fetch origin
  local i=0
  while [ $i -lt ${#NAMES[@]} ]; do
    local p="${PATHS[$i]}" n="${NAMES[$i]}"
    echo "→ rebase $n ($p)"
    if ! git -C "$p" rebase origin/main; then
      echo "  ! conflict ở '$n' — ĐÃ DỪNG, chưa resolve."
      echo "    Vào $p xử lý tay rồi \`git rebase --continue\` (hoặc --abort)."
    fi
    i=$((i+1))
  done
}

cmd_kill() {
  local name="${1:?dùng: agents kill <name>}"
  ai-devkit agent kill "$name" >/dev/null 2>&1 || true
  if tmux kill-session -t "$(tmux_name "$name")" 2>/dev/null; then
    echo "killed $name"
  else
    echo "'$name' không chạy"
  fi
}

cmd_kill_all() {
  printf "Kill tất cả agent (%s)? (y/N) " "$(IFS=' '; echo "${NAMES[*]}")"
  read -r reply
  case "$reply" in [Yy]*) ;; *) echo "huỷ"; return 1 ;; esac
  local i=0
  while [ $i -lt ${#NAMES[@]} ]; do cmd_kill "${NAMES[$i]}"; i=$((i+1)); done
}

# --- dự phòng khi ai-devkit console lag: gọi CLI trực tiếp ---
# Lưu ý: ai-devkit dùng TÊN RIÊNG của nó (vd myapp-glossary-16713); tên tmux
# 'glossary' thường khớp nhờ so trùng một phần. Không chắc thì xem `agents ls`.
cmd_send() {
  local name="${1:?dùng: agents send <name> \"lời nhắn\"}"; shift
  [ $# -gt 0 ] || { echo "thiếu lời nhắn"; return 1; }
  ai-devkit agent send --id "$name" "$*"
}

cmd_detail() {
  local name="${1:?dùng: agents detail <name>}"
  ai-devkit agent detail --id "$name" --tail 20
}

# Session tmux riêng cho console: pane trên = ai-devkit console, pane dưới = shell.
# Pane nhỏ (50/50) + tmux tiết chế redraw -> né lag. Độc lập với mọi agent session.
cmd_console() {
  local s="$CONSOLE_SESSION"
  if ! tmux has-session -t "$s" 2>/dev/null; then
    tmux new-session -d -s "$s" -c "$BASE" 'ai-devkit agent console'
    tmux split-window -v -t "$s" -c "$BASE"   # pane dưới = shell; thành pane active
    echo "+ tạo session '$s' (console + shell)"
  fi
  if [ -n "${TMUX:-}" ]; then tmux switch-client -t "$s"; else tmux attach -t "$s"; fi
}

usage() {
  sed -n '2,/^set /p' "$0" | grep '^#' | sed 's/^# \{0,1\}//'
}

load_agents
case "${1:-}" in
  up|resume)    cmd_up ;;
  new|recreate) shift; cmd_new "$@" ;;
  open|attach)  shift; cmd_open "$@" ;;
  ls|status)    cmd_ls ;;
  sync)         cmd_sync ;;
  kill)         shift; cmd_kill "$@" ;;
  kill-all)     cmd_kill_all ;;
  send|msg)     shift; cmd_send "$@" ;;
  detail)       shift; cmd_detail "$@" ;;
  console|con)  cmd_console ;;
  ""|-h|--help|help) usage ;;
  *) echo "lệnh lạ: $1"; echo; usage; exit 1 ;;
esac

bash -n ~/bin/agents.sh && echo OK

alias agents-a='AGENTS_PROJECT=myapp  AGENTS_BASE=$HOME/projects/a AGENTS_SESSION_PREFIX=a- ~/bin/agents.sh'
alias agents-b='AGENTS_PROJECT=other  AGENTS_BASE=$HOME/projects/b AGENTS_SESSION_PREFIX=b- ~/bin/agents.sh'

git -C "$MAIN" worktree list --porcelain

worktree /home/you/projects/myapp-workspace/myapp
HEAD 97f6a49...
branch refs/heads/main
                              ← dòng trống ngăn cách entry
worktree /home/you/projects/myapp-workspace/myapp-glossary
HEAD 97f6a49...
branch refs/heads/feat/glossary

tmux new-session -d -s "$(tmux_name "$name")" -c "$path" "$CLAUDE_CONT"

tmux kill-session -t "$(tmux_name "$name")" 2>/dev/null || true
start_one "$name"

if [ -n "${TMUX:-}" ]; then tmux switch-client -t "$t"; else tmux attach -t "$t"; fi

=== worktree / agent ===
  main         ngủ  /home/you/projects/myapp-workspace/myapp
  blog         chạy /home/you/projects/myapp-workspace/myapp-blog
  glossary     chạy /home/you/projects/myapp-workspace/myapp-glossary

=== ai-devkit discover ===
  Agent                 Project         Status   Working On
  myapp-blog-36929      myapp-blog      🟢 run   Viết mục Ubuntu...
  myapp-glossary-62943  myapp-glossary  ⚪ idle  ...

git -C "$MAIN" fetch origin
# rồi với từng worktree:
git -C "$p" rebase origin/main

ai-devkit agent send   --id "$name" "$*"
ai-devkit agent detail --id "$name" --tail 20

agents send glossary "chạy npm run lint rồi commit theo Conventional Commits"
agents detail glossary

sed -n '2,/^set /p' "$0" | grep '^#' | sed 's/^# \{0,1\}//'

alias agents="~/bin/agents.sh"
alias devsession="~/bin/session.sh"    # xem mục 13

alias agents="$HOME/bin/agents.sh"
alias devsession="$HOME/bin/session.sh"

source ~/.zshrc     # hoặc: source ~/.bashrc

agents up          # bật mọi agent feature còn thiếu
agents ls          # xem cái nào chạy, cái nào đang chờ input

agents open glossary       # vào session, gõ prompt như bình thường
# Ctrl-b d để detach — agent vẫn chạy tiếp

agents send glossary "thêm deep-link cho từng thuật ngữ, chạy lint trước khi commit"

agents console             # TUI, xem tất cả trong một màn hình
# hoặc rẻ hơn:
watch -n5 ~/bin/agents.sh ls

agents sync                # fetch + rebase origin/main cho mọi worktree

cd "$BASE/myapp"
git worktree add -b feat/search "$BASE/myapp-search" origin/main
agents new search          # script tự thấy worktree mới, không cần sửa gì

agents kill-all            # hoặc cứ để chạy; kill không mất context

/model claude-opus-5

AGENT_MODEL="${AGENTS_MODEL:-claude-opus-5}"
CLAUDE_CONT="${AGENTS_CMD:-claude --continue --model $AGENT_MODEL || claude --model $AGENT_MODEL}"

# 1. Cập nhật binary — chạy ở shell riêng, KHÔNG chạy trong session agent
claude update

# 2. Sửa AGENT_MODEL trong ~/bin/agents.sh (hoặc để mặc định rồi override)

# 3. Phóng lại toàn bộ agent
agents kill-all && agents up

AGENTS_MODEL=claude-fable-5 agents up

tmux attach -t glossary
tmux ls                    # liệt kê session

agents console
# pane dưới là shell trống — dùng để chạy git, agents send, xem log
# Ctrl-b ↑ / ↓ chuyển giữa hai pane

agents ls                       # thay cho mở console chỉ để xem trạng thái
agents detail glossary          # thay cho cuộn tìm trong TUI
agents send glossary "..."      # thay cho gõ vào TUI

pkill -f "ai-devkit.*agent console"

#!/usr/bin/env bash
# session.sh — dựng lại toàn bộ tmux session sau khi khởi động lại máy:
#   dev server + API + mỗi agent một window + console.
#
# Dùng:
#   ./session.sh          # dựng lại (hoặc attach nếu đã có) rồi vào session
#   ./session.sh --resume # dùng `claude --resume` (picker) thay vì --continue
#   ./session.sh --kill   # kill session

set -euo pipefail

# ─────────── SỬA CHO PROJECT CỦA BẠN ───────────
PROJECT="${AGENTS_PROJECT:-myapp}"
SESSION="$PROJECT"
BASE="${AGENTS_BASE:-$HOME/projects/$PROJECT-workspace}"
APP_DIR="$BASE/$PROJECT"              # app chính (worktree main)
API_DIR="$BASE/$PROJECT-api"          # backend, bỏ trống nếu không có

# Danh sách agent: "tên:đường-dẫn-worktree"
# Đường dẫn phải CHÍNH XÁC, vì `claude --continue` resume theo cwd.
AGENTS="
glossary:$BASE/$PROJECT-glossary
blog:$BASE/$PROJECT-blog
"
# ───────────────────────────────────────────────

CLAUDE_CMD="claude --continue"

case "${1:-}" in
  --resume) CLAUDE_CMD="claude --resume" ;;
  --kill)   tmux kill-session -t "$SESSION" 2>/dev/null && echo "killed $SESSION"; exit 0 ;;
esac

# Đã có session -> attach luôn, không dựng lại
if tmux has-session -t "$SESSION" 2>/dev/null; then
  echo "Session '$SESSION' đã tồn tại — attaching."
  exec tmux attach -t "$SESSION"
fi

# --- window 0: main (shell trống để chạy git/ai-devkit) ---
tmux new-session -d -s "$SESSION" -n main -c "$BASE"

# --- window: dev (2 pane: app + api) ---
if [ -d "$APP_DIR" ]; then
  tmux new-window -t "$SESSION" -n dev -c "$APP_DIR"
  tmux send-keys -t "$SESSION:dev" 'npm run dev' C-m
  if [ -d "$API_DIR" ]; then
    tmux split-window -h -t "$SESSION:dev" -c "$API_DIR"
    tmux send-keys -t "$SESSION:dev.1" 'npm start' C-m
  fi
fi

# --- mỗi agent một window riêng ---
echo "$AGENTS" | while IFS= read -r entry; do
  [ -z "$entry" ] && continue
  name="${entry%%:*}"
  path="${entry#*:}"

  if [ ! -d "$path" ]; then
    echo "  ! bỏ qua '$name' — không tìm thấy $path"
    continue
  fi

  tmux new-window -t "$SESSION" -n "$name" -c "$path"
  # --continue fail nếu worktree chưa từng có phiên -> fallback sang claude trần
  tmux send-keys -t "$SESSION:$name" "$CLAUDE_CMD || claude" C-m
  echo "  + $name -> $path"
done

# --- window: console (ai-devkit TUI) ---
tmux new-window -t "$SESSION" -n console -c "$BASE"
tmux send-keys -t "$SESSION:console" 'ai-devkit agent console' C-m

tmux select-window -t "$SESSION:main"
exec tmux attach -t "$SESSION"

cd "$BASE/myapp-glossary"
git status                  # xem file conflict
# sửa file...
git add -A && git rebase --continue
# hoặc bỏ cuộc:
git rebase --abort

## Quy ước commit
Conventional Commits: `<type>(<scope>): <mô tả>`, imperative, ≤72 ký tự, không dấu chấm cuối.
Mỗi commit một thay đổi logic. Chạy `npm run lint` trước khi commit.
Không thêm co-author hay footer quảng cáo tool.

## Tuyệt đối không
Không `git push`, không `--force`, không `git reset --hard`, không sửa lịch sử.
Đồng bộ với main: `git rebase origin/main`, KHÔNG `git merge main`.

sudo apt update
sudo apt install -y tmux git curl

# Node.js — apt thường có bản quá cũ cho claude/ai-devkit; dùng nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec "$SHELL" -l
nvm install --lts
node -v            # cần ≥ 18

# ai-devkit
npm i -g ai-devkit
# (hoặc không cài global: npx ai-devkit@latest agent list)

# Claude Code — native installer
curl -fsSL https://claude.ai/install.sh | bash
# hoặc qua npm:
npm i -g @anthropic-ai/claude-code

cat >> ~/.bashrc <<'EOF'

# --- multi-agent ---
export PATH="$HOME/bin:$PATH"
alias agents="$HOME/bin/agents.sh"
alias devsession="$HOME/bin/session.sh"
EOF

source ~/.bashrc

bash -n ~/bin/agents.sh  && echo "agents.sh OK"
bash -n ~/bin/session.sh && echo "session.sh OK"
chmod +x ~/bin/agents.sh ~/bin/session.sh

export AGENTS_BASE="$HOME/projects/myapp-workspace"
mkdir -p "$AGENTS_BASE"

BASE="${AGENTS_BASE:-$HOME/projects/$PROJECT-workspace}"

sudo apt install -y kitty          # có sẵn trong apt
sudo apt install -y alacritty      # có sẵn trong apt (hoặc snap/cargo)
# Ghostty: tải .deb từ trang chủ (có bản Linux)
# WezTerm: tải .deb từ GitHub releases

/tmp/tmux-$(id -u)/default

ls -la /tmp/tmux-$(id -u)/          # xem socket
tmux ls                             # liệt kê session trên socket mặc định
tmux -L myproj new -s glossary      # dùng SOCKET RIÊNG tên 'myproj' — cách ly tuyệt đối
pkill -f "ai-devkit.*agent console" # thoát console kẹt (không đụng agent)

AGENTS_TMUX_SOCKET=myproj agents up    # mọi lệnh tmux trong script chạy trên socket 'myproj'
AGENTS_TMUX_SOCKET=myproj agents ls
tmux -L myproj ls                      # gõ tmux tay thì phải tự thêm -L

alias agents='AGENTS_TMUX_SOCKET=myproj $HOME/bin/agents.sh'

ssh you@server
agents up
agents ls
# Ctrl-b d rồi thoát SSH — agent vẫn chạy tiếp

[ ] Cài tmux, git, Node ≥18, claude, ai-devkit
[ ] Cài một terminal GPU (Ghostty / kitty / Alacritty / WezTerm)
[ ] Tạo thư mục BASE, clone repo main vào $BASE/<project>
[ ] Tạo worktree theo quy ước tên: <project>-<agent>
[ ] Lưu agents.sh vào ~/bin, sửa 4 biến ở đầu (PROJECT, BASE, MAIN, AGENT_MODEL)
[ ] chmod +x ~/bin/agents.sh && bash -n ~/bin/agents.sh
[ ] Thêm alias vào ~/.zshrc (macOS) hoặc ~/.bashrc (Ubuntu)
[ ] agents ls  → thấy đủ worktree
[ ] agents up  → agent lên
[ ] agents open <name> → gõ được prompt, Ctrl-b d thoát
[ ] agents console → TUI hiện đủ agent
[ ] (tuỳ chọn) session.sh cho one-command restore sau reboot
[ ] Viết CLAUDE.md ở gốc repo: quy ước commit, cấm push/force