名称： claude-team
描述： 通过 iTerm2 使用 claude-team MCP 服务器编排多个 Claude Code 工作进程。通过 git worktree 创建工作进程、分配 beads 任务、监控进度并协调并行开发工作。
主页： https://github.com/Martian-Engineering/claude-team
元数据： {"clawdbot":{"emoji":"👥","os":["darwin"],"requires":{"bins":["mcporter"]}}}

Claude Team

Claude-team 是一个 MCP 服务器，允许你通过 iTerm2 创建和管理多个 Claude Code 会话团队。每个工作进程拥有独立的终端窗格、可选的 git worktree，并可分配 beads 任务。

为什么使用 Claude Team？

• 并行处理：将工作分发给多个同时运行的智能体
• 上下文隔离：每个工作进程拥有全新的上下文，保持协调者上下文清洁
• 可视化监控：可实时观察、中断或接管真实的 Claude Code 会话
• Git worktree：每个工作进程可在独立分支上进行工作

⚠️ 重要规则

切勿直接修改代码。 始终通过创建工作进程来执行代码变更。这能保持你的上下文清洁，并通过 worktree 提供正确的 git 工作流。

前提条件

• 安装 iTerm2 的 macOS（需启用 Python API：Preferences → General → Magic → Enable Python API）
• 在 ~/.claude.json 中配置 claude-team MCP 服务器

通过 mcporter 使用

所有工具都通过 mcporter call claude-team.<工具名> 调用：

mcporter call claude-team.list_workers
mcporter call claude-team.spawn_workers workers='[{"project_path":"/path/to/repo","bead":"cp-123"}]'

核心工具

spawn_workers

创建新的 Claude Code 工作进程会话。

mcporter call claude-team.spawn_workers \
  workers='[{
    "project_path": "/path/to/repo",
    "bead": "cp-123",
    "annotation": "修复认证错误",
    "use_worktree": true,
    "skip_permissions": true
  }]' \
  layout="auto"

工作进程配置字段：
- project_path：必需。仓库路径或 "auto"（使用 CLAUDE_TEAM_PROJECT_DIR 环境变量）
- bead：可选的 beads 任务 ID — 工作进程将遵循 beads 工作流
- annotation：任务描述（显示在徽章上，用于分支命名）
- prompt：附加指令（若无 bead，则作为任务分配）
- use_worktree：创建隔离的 git worktree（默认：true）
- skip_permissions：以 --dangerously-skip-permissions 启动（默认：false）
- name：可选的工作进程名称覆盖（否则从主题集中自动选择）

布局选项：
- "auto"：复用现有的 claude-team 窗口，在可用空间内分割
- "new"：始终创建新窗口（1-4 个工作进程采用网格布局）

list_workers

查看所有受管理的工作进程：

mcporter call claude-team.list_workers
mcporter call claude-team.list_workers status_filter="ready"

状态值：spawning、ready、busy、closed

message_workers

向一个或多个工作进程发送消息：

mcporter call claude-team.message_workers \
  session_ids='["Groucho"]' \
  message="请同时添加单元测试" \
  wait_mode="none"

wait_mode 选项：
- "none"：发送后不等待（默认）
- "any"：任一工作进程空闲时返回
- "all"：所有工作进程空闲时返回

check_idle_workers / wait_idle_workers

检查或等待工作进程完成：

# 快速轮询
mcporter call claude-team.check_idle_workers session_ids='["Groucho","Harpo"]'

# 阻塞等待
mcporter call claude-team.wait_idle_workers \
  session_ids='["Groucho","Harpo"]' \
  mode="all" \
  timeout=600

read_worker_logs

获取对话历史：

mcporter call claude-team.read_worker_logs \
  session_id="Groucho" \
  pages=2

examine_worker

获取详细状态（包括对话统计）：

mcporter call claude-team.examine_worker session_id="Groucho"

close_workers

完成后终止工作进程：

mcporter call claude-team.close_workers session_ids='["Groucho","Harpo"]'

⚠️ Worktree 清理：使用 worktree 的工作进程会将更改提交到临时分支。关闭后：
1. 在工作进程分支上审查提交
2. 合并或 cherry-pick 到持久分支
3. 删除分支：git branch -D <分支名>

bd_help

beads 命令快速参考：

mcporter call claude-team.bd_help

工作进程标识

工作进程可通过以下任一方式引用：
- 内部 ID：短十六进制字符串（如 3962c5c4）
- 终端 ID：iterm:UUID 格式
- 工作进程名称：人类友好名称（如 Groucho、Aragorn）

工作流：分配 Beads 任务

# 1. 创建分配了 bead 任务的工作进程
mcporter call claude-team.spawn_workers \
  workers='[{
    "project_path": "/Users/phaedrus/Projects/myrepo",
    "bead": "proj-abc",
    "annotation": "实现配置模式",
    "use_worktree": true,
    "skip_permissions": true
  }]'

# 2. 工作进程自动执行：
#    - 创建以 bead 命名的分支 worktree
#    - 运行 `bd show proj-abc` 理解任务
#    - 将任务标记为 in_progress
#    - 实施工作
#    - 关闭任务
#    - 提交并引用任务

# 3. 监控进度
mcporter call claude-team.check_idle_workers session_ids='["Groucho"]'
mcporter call claude-team.read_worker_logs session_id="Groucho"

# 4. 完成后关闭并合并
mcporter call claude-team.close_workers session_ids='["Groucho"]'
# 然后：从工作进程分支执行 git merge 或 cherry-pick

工作流：并行分发

# 为并行任务创建多个工作进程
mcporter call claude-team.spawn_workers \
  workers='[
    {"project_path": "auto", "bead": "cp-123", "annotation": "认证模块"},
    {"project_path": "auto", "bead": "cp-124", "annotation": "API 路由"},
    {"project_path": "auto", "bead": "cp-125", "annotation": "单元测试"}
  ]' \
  layout="new"

# 等待所有工作进程完成
mcporter call claude-team.wait_idle_workers \
  session_ids='["Groucho","Harpo","Chico"]' \
  mode="all"

# 审查并关闭
mcporter call claude-team.close_workers \
  session_ids='["Groucho","Harpo","Chico"]'

最佳实践

1. 使用 beads：分配 bead ID 使工作进程遵循正确的任务工作流
2. 使用 worktree：保持工作隔离，支持并行提交
3. 跳过权限检查：工作进程需要 skip_permissions: true 才能写入文件
4. 监控而非微管理：让工作进程完成，然后审查
5. 谨慎合并：合并到主分支前审查工作进程分支
6. 关闭工作进程：完成后始终关闭以清理 worktree

HTTP 模式（Streamable HTTP 传输）

为支持持久化服务器操作，claude-team 可作为 HTTP 服务器运行。这使 MCP 服务器持续运行并保持持久状态，避免冷启动。

启动 HTTP 服务器

直接运行 claude-team HTTP 服务器：

# 从 claude-team 目录
uv run python -m claude_team_mcp --http --port 8766

# 或显式指定目录
uv run --directory /path/to/claude-team python -m claude_team_mcp --http --port 8766

如需登录时自动启动，请使用 launchd（参见下文“launchd 自动启动”部分）。

mcporter.json 配置

HTTP 服务器运行后，配置 mcporter 连接。创建 ~/.mcporter/mcporter.json：

{
  "mcpServers": {
    "claude-team": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:8766/mcp",
      "lifecycle": "keep-alive"
    }
  }
}

HTTP 模式的优势

• 持久状态：工作进程注册表在 CLI 调用间保持
• 更快响应：每次调用无需启动 Python 环境
• 外部访问：可由 cron 任务、脚本或其他工具访问
• 会话恢复：即使协调者断开连接，服务器仍跟踪会话

从 Claude Code 连接

更新 .mcp.json 以使用 HTTP 传输：

{
  "mcpServers": {
    "claude-team": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:8766/mcp"
    }
  }
}

launchd 自动启动

要自动在登录时启动 claude-team 服务器，请使用捆绑的设置脚本。

快速设置

从技能的资源目录运行设置脚本：

# 从技能目录
./assets/setup.sh

# 或指定自定义 claude-team 位置
CLAUDE_TEAM_DIR=/path/to/claude-team ./assets/setup.sh

设置脚本的功能

设置脚本：
1. 检测你的 uv 安装路径
2. 在 ~/.claude-team/logs/ 创建日志目录
3. 从 assets/com.claude-team.plist.template 生成 launchd plist
4. 安装到 ~/Library/LaunchAgents/com.claude-team.plist
5. 加载服务以立即启动

plist 模板使用 uv run 在端口 8766 启动 HTTP 服务器，配置为 iTerm2 Python API 访问（Aqua 会话类型）。

管理服务

# 停止服务
launchctl unload ~/Library/LaunchAgents/com.claude-team.plist

# 重启（重新运行设置）
./assets/setup.sh

# 检查是否运行
launchctl list | grep claude-team

# 查看日志
tail -f ~/.claude-team/logs/stdout.log
tail -f ~/.claude-team/logs/stderr.log

launchd 故障排除

# 检查加载错误
launchctl print gui/$UID/com.claude-team

# 强制重启
launchctl kickstart -k gui/$UID/com.claude-team

# 移除并重新加载（如果 plist 已更改）
launchctl bootout gui/$UID/com.claude-team
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.claude-team.plist

Cron 集成

为支持后台监控和通知，claude-team 支持基于 cron 的工作进程跟踪。

工作进程跟踪文件

Claude-team 将工作进程状态写入 ~/.claude-team/memory/worker-tracking.json：

{
  "workers": {
    "Groucho": {
      "session_id": "3962c5c4",
      "bead": "cp-123",
      "annotation": "修复认证错误",
      "status": "busy",
      "project_path": "/Users/phaedrus/Projects/myrepo",
      "started_at": "2025-01-05T10:30:00Z",
      "last_activity": "2025-01-05T11:45:00Z"
    },
    "Harpo": {
      "session_id": "a1b2c3d4",
      "bead": "cp-124",
      "annotation": "添加 API 路由",
      "status": "idle",
      "project_path": "/Users/phaedrus/Projects/myrepo",
      "started_at": "2025-01-05T10:30:00Z",
      "last_activity": "2025-01-05T11:50:00Z",
      "completed_at": "2025-01-05T11:50:00Z"
    }
  },
  "last_updated": "2025-01-05T11:50:00Z"
}

监控完成情况的 Cron 任务

在 ~/.claude-team/scripts/check-workers.sh 创建监控脚本：

#!/bin/bash
# 检查已完成的工作进程并发送通知

TRACKING_FILE="$HOME/.claude-team/memory/worker-tracking.json"
NOTIFIED_FILE="$HOME/.claude-team/memory/notified-workers.json"
TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN}"
TELEGRAM_CHAT_ID="${TELEGRAM_CHAT_ID}"

# 如果跟踪文件不存在则退出
[ -f "$TRACKING_FILE" ] || exit 0

# 如果需要则初始化通知文件
[ -f "$NOTIFIED_FILE" ] || echo '{"notified":[]}' > "$NOTIFIED_FILE"

# 查找空闲且未通知的工作进程
IDLE_WORKERS=$(jq -r '
  .workers | to_entries[] |
  select(.value.status == "idle") |
  .key
' "$TRACKING_FILE")

for worker in $IDLE_WORKERS; do
  # 检查是否已通知
  ALREADY_NOTIFIED=$(jq -r --arg w "$worker" '.notified | index($w) != null' "$NOTIFIED_FILE")

  if [ "$ALREADY_NOTIFIED" = "false" ]; then
    # 获取工作进程详情
    BEAD=$(jq -r --arg w "$worker" '.workers[$w].bead // "no-bead"' "$TRACKING_FILE")
    ANNOTATION=$(jq -r --arg w "$worker" '.workers[$w].annotation // "no annotation"' "$TRACKING_FILE")

    # 发送 Telegram 通知
    MESSAGE="🤖 工作进程 *${worker}* 已完成
📋 任务：\`${BEAD}\`
📝 ${ANNOTATION}"

    curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
      -d chat_id="$TELEGRAM_CHAT_ID" \
      -d text="$MESSAGE" \
      -d parse_mode="Markdown" > /dev/null

    # 标记为已通知
    jq --arg w "$worker" '.notified += [$w]' "$NOTIFIED_FILE" > "${NOTIFIED_FILE}.tmp"
    mv "${NOTIFIED_FILE}.tmp" "$NOTIFIED_FILE"
  fi
done

使其可执行：

chmod +x ~/.claude-team/scripts/check-workers.sh

Crontab 条目

添加到 crontab（crontab -e）：

# 每 2 分钟检查 claude-team 工作进程
*/2 * * * * TELEGRAM_BOT_TOKEN="your-bot-token" TELEGRAM_CHAT_ID="your-chat-id" ~/.claude-team/scripts/check-workers.sh

环境设置

在 shell 配置文件（~/.zshrc）中设置 Telegram 凭据：

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
export TELEGRAM_CHAT_ID="-1001234567890"

替代方案：使用 clawdbot 发送通知

如果已配置 clawdbot，可通过它发送通知：

# 在 check-workers.sh 中，替换 curl 命令为：
clawdbot send --to "$TELEGRAM_CHAT_ID" --message "$MESSAGE" --provider telegram

清除通知状态

开始新一批工作进程时，清除通知列表：

echo '{"notified":[]}' > ~/.claude-team/memory/notified-workers.json