┌──────────────────────────────────────────────────────────────────┐
│  你的 VS Code / 主会话                                            │
│                                                                   │
│  用自然语言管理团队、启动终端、分配总任务                             │
│       ↓                                                           │
│  MCP Server (FastMCP)  ←── teams_data.json (持久化)               │
│       ↓                                                           │
│  ┌─ tmux session: mcp_dev_team ─────────────────────────────────┐ │
│  │  window: 👑alice (leader · codex)  ← 自动连接 MCP            │ │
│  │  window: bob   (coder  · claude)  ← 纯文本接收子任务         │ │
│  │  window: carol (tester · codex)   ← 纯文本接收子任务         │ │
│  └──────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

git clone https://github.com/davidzong1/Mult-Agent-MCP.git
cd mult_agent_mcp
./install.sh
source ~/.bashrc

pip install -r requirements.txt

tmux -V

# Ubuntu / Debian
sudo apt install tmux
pip install textual

# macOS
brew install tmux

# Claude Code
npm install -g @anthropic-ai/claude-code

# Codex CLI（需要 Node.js ≥ 22，ChatGPT Plus/Pro 账号或 API Key）
npm install -g @openai/codex

{
  "mcpServers": {
    "mult-agent-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

codex mcp add mult-agent-mcp --url http://localhost:8000/mcp

cd mult_agent_mcp
python mult_agent_mcp.py
# 或指定端口
FASTMCP_PORT=8000 python mult_agent_mcp.py

teammcp

TUI 添加团队 ─→ teams_data.json ←─ MCP Server team_create
TUI 添加成员 ─→ teams_data.json ←─ MCP Server add_member
TUI 指定Leader ─→ teams_data.json ←─ MCP Server set_leader

> 创建一个团队叫 dream_team，默认 agent 用 claude。
  添加三个成员：
  alice（role=leader, agent=codex），
  bob（role=coder, agent=claude），
  carol（role=tester, agent=codex）

team_create("dream_team", "混合 agent 团队", default_agent="claude")
add_member("dream_team", "alice", role="leader", agent="codex")
add_member("dream_team", "bob",   role="coder",  agent="claude")
add_member("dream_team", "carol", role="tester",  agent="codex")
set_leader("dream_team", "alice")

> 启动 dream_team 的终端，任务是"实现用户登录系统"

> 查看团队
→ leader_list_team("dream_team")
→ bob(coder · claude), carol(tester · codex)

> 让 bob 实现登录页面，让 carol 写测试用例
→ leader_assign_subtask("dream_team", "bob", "实现登录页面...")
→ leader_assign_subtask("dream_team", "carol", "写登录测试用例...")

> 查看终端状态
→ terminal_status("dream_team")

> 关闭所有终端
→ kill_team_terminals("dream_team")

你 ─→ MCP ─→ launch_team_terminals ─→ [alice tmux] ─→ leader_* ─→ [bob] [carol]

claim_leader("dream_team")
# 如果旧 leader 存活 → 自动降级为普通成员
# 如果旧 leader 已死 → 直接接管

# 直接在当前会话分配任务
leader_assign_subtask("dream_team", "bob", "实现登录页面")
leader_broadcast("dream_team", "进度更新：前端完成 30%")

# 释放
unclaim_leader("dream_team", restore_member="alice")

# 创建团队
team_create("mixed_team", default_agent="claude")

# Claude 作为 leader + Codex 作为成员
add_member("mixed_team", "alice", role="leader", agent="claude")
add_member("mixed_team", "bob",   role="coder",  agent="codex")
add_member("mixed_team", "carol", role="tester",  agent="codex")
set_leader("mixed_team", "alice")

# 或者反过来——Codex 作为 leader
add_member("mixed_team", "dave", role="backend_dev", agent="claude")
member_set_agent("mixed_team", "alice", "codex")  # 切换 leader 类型
launch_team_terminals("mixed_team", task="实现微服务架构")

# 检查 agent 配置状态
check_agent_setup("mixed_team")
→ Claude MCP: ✅
→ Codex MCP: ✅

# 也可以手动在终端执行
codex mcp add mult-agent-mcp --url http://localhost:8000/mcp
codex mcp list

leader_assign_subtask("team", "bob", "实现登录页面")
          │
          ▼
tmux send-keys -t mcp_team:bob "实现登录页面" Enter
          │
          ▼
bob 的终端窗口收到文本 → claude 或 codex 开始执行

leader_read_member_terminal("team", "bob")         # 查看成员是否停在 approval prompt
leader_authorize_member("team", "bob", "yes")      # 选择第 1 项，通常为本次允许
leader_authorize_member("team", "bob", "session")  # 选择第 2 项，通常为本会话记住
leader_authorize_member("team", "bob", "3")        # 选择第 3 项，具体含义以终端提示为准

claim_leader("team")
        │
        ├── 已经是 direct leader
        │   → 提示"你已经是 leader"
        │
        ├── 之前无 leader
        │   → 🆕 设为直接控制模式
        │
        ├── 有 tmux leader 且终端存活
        │   → 🔄 原 leader 降级为普通成员（窗口保留）
        │   → ✅ 你接管为 leader
        │
        └── 有 tmux leader 但终端已死
            → 💀 直接接管，清理死引用

{
  "teams": {
    "dream_team": {
      "description": "混合 agent 团队",
      "leader": "alice",
      "leader_type": "tmux",
      "default_agent": "claude",
      "terminals_active": true,
      "members": {
        "alice": {"role": "leader", "model": "", "agent": "codex"},
        "bob":   {"role": "coder",  "model": "", "agent": "claude"},
        "carol": {"role": "tester", "model": "", "agent": "codex"}
      }
    }
  }
}

# 查看团队终端
tmux attach -t mcp_dev_team

# 在 tmux 中: Ctrl+B 然后按数字键 → 切换窗口
# 在 tmux 中: Ctrl+B 然后按 W → 列出所有窗口
# 在 tmux 中: Ctrl+B 然后按 D → 脱离（不关闭）

tmux list-sessions              # 列出所有 session
tmux list-windows -t mcp_dev_team  # 列出某 session 的窗口