介绍
# Claude Team
Claude-team 是一个 MCP 服务器，允许你通过 iTerm2 生成和管理多个 Claude Code 会话团队。每个 worker 都拥有自己的终端窗格、可选的 git worktree，并且可以被分配 beads issues。
## 为什么使用 Claude Team？
- **并行性**：将工作分发到多个同时工作的代理 - **上下文隔离**：每个 worker 都有全新的上下文，保持协调器上下文整洁 - **可见性**：你可以观看、中断或接管的实时 Claude Code 会话 - **Git worktrees**：每个 worker 可以拥有用于其工作的隔离分支
## ⚠️ 重要规则
**切勿直接修改代码。** 始终为代码修改生成 worker。这可以保持你的上下文整洁，并提供使用 worktree 的适当 git 工作流程。
## 前置条件
- 安装了 iTerm2 的 macOS（启用 Python API：Preferences → General → Magic → Enable Python API） - 在 `~/.claude.json` 中配置了 claude-team MCP 服务器
## 通过 mcporter 使用
所有工具都通过 `mcporter call claude-team.<tool>` 调用：
```bash 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 worker 会话。
```bash mcporter call claude-team.spawn_workers \ workers='[{ "project_path": "/path/to/repo", "bead": "cp-123", "annotation": "Fix auth bug", "use_worktree": true, "skip_permissions": true }]' \ layout="auto" ```
**Worker 配置字段：** - `project_path`：必需。仓库路径或 "auto"（使用 CLAUDE_TEAM_PROJECT_DIR） - `bead`：可选的 beads issue ID —— worker 将遵循 beads 工作流程 - `annotation`：任务描述（显示在徽章上，用于分支名称） - `prompt`：附加指令（如果没有 bead，则作为分配给它的任务） - `use_worktree`：创建隔离的 git worktree（默认：true） - `skip_permissions`：使用 --dangerously-skip-permissions 启动（默认：false） - `name`：可选的 worker 名称覆盖（否则自动从主题集合中选择）
**布局选项：** - `"auto"`：重用现有的 claude-team 窗口，分割到可用空间 - `"new"`：始终创建新窗口（1-4 个 worker 以网格布局排列）
### list_workers
查看所有管理的 worker：
```bash mcporter call claude-team.list_workers mcporter call claude-team.list_workers status_filter="ready" ```
状态值：`spawning`、`ready`、`busy`、`closed`
### message_workers
向一个或多个 worker 发送消息：
```bash mcporter call claude-team.message_workers \ session_ids='["Groucho"]' \ message="Please also add unit tests" \ wait_mode="none" ```
**wait_mode 选项：** - `"none"`：即发即弃（默认） - `"any"`：当任意 worker 空闲时返回 - `"all"`：当所有 worker 空闲时返回
### check_idle_workers / wait_idle_workers
检查或等待 worker 完成：
```bash # Quick poll mcporter call claude-team.check_idle_workers session_ids='["Groucho","Harpo"]'
# Blocking wait mcporter call claude-team.wait_idle_workers \ session_ids='["Groucho","Harpo"]' \ mode="all" \ timeout=600 ```
### read_worker_logs
获取对话历史：
```bash mcporter call claude-team.read_worker_logs \ session_id="Groucho" \ pages=2 ```
### examine_worker
获取包括对话统计在内的详细状态：
```bash mcporter call claude-team.examine_worker session_id="Groucho" ```
### close_workers
完成后终止 worker：
```bash mcporter call claude-team.close_workers session_ids='["Groucho","Harpo"]' ```
⚠️ **Worktree 清理**：具有 worktree 的 worker 会提交到临时分支。关闭后： 1. 检查 worker 分支上的提交 2. 合并或挑选到持久分支 3. 删除分支：`git branch -D <branch-name>`
### bd_help
Beads 命令的快速参考：
```bash mcporter call claude-team.bd_help ```
## Worker 识别
Worker 可以通过以下任一方式引用： - **内部 ID**：短十六进制字符串（例如 `3962c5c4`） - **终端 ID**：`iterm:UUID` 格式 - **Worker 名称**：人性化的名称（例如 `Groucho`、`Aragorn`）
## 工作流程：分配 Beads Issue
```bash # 1. Spawn worker with a bead assignment mcporter call claude-team.spawn_workers \ workers='[{ "project_path": "/Users/phaedrus/Projects/myrepo", "bead": "proj-abc", "annotation": "Implement config schemas", "use_worktree": true, "skip_permissions": true }]'
# 2. Worker automatically: # - Creates worktree with branch named after bead # - Runs `bd show proj-abc` to understand the task # - Marks issue in_progress # - Implements the work # - Closes the issue # - Commits with issue reference
# 3. Monitor progress mcporter call claude-team.check_idle_workers session_ids='["Groucho"]' mcporter call claude-team.read_worker_logs session_id="Groucho"
# 4. When done, close and merge mcporter call claude-team.close_workers session_ids='["Groucho"]' # Then: git merge or cherry-pick from worker's branch ```
## 工作流程：并行分发
```bash # Spawn multiple workers for parallel tasks mcporter call claude-team.spawn_workers \ workers='[ {"project_path": "auto", "bead": "cp-123", "annotation": "Auth module"}, {"project_path": "auto", "bead": "cp-124", "annotation": "API routes"}, {"project_path": "auto", "bead": "cp-125", "annotation": "Unit tests"} ]' \ layout="new"
# Wait for all to complete mcporter call claude-team.wait_idle_workers \ session_ids='["Groucho","Harpo","Chico"]' \ mode="all"
# Review and close mcporter call claude-team.close_workers \ session_ids='["Groucho","Harpo","Chico"]' ```
## 最佳实践
1. **使用 beads**：分配 `bead` ID，以便 worker 遵循正确的 issue 工作流程 2. **使用 worktrees**：保持工作隔离，启用并行提交 3. **跳过权限**：Worker 需要 `skip_permissions: true` 才能写入文件 4. **监控，不要微观管理**：让 worker 完成，然后审查 5. **谨慎合并**：合并到 main 之前审查 worker 分支 6. **关闭 worker**：完成后务必关闭以清理 worktrees
## HTTP 模式（可流式 HTTP 传输）
对于持久服务器操作，claude-team 可以作为 HTTP 服务器运行。这使 MCP 服务器保持持续运行并具有持久状态，避免冷启动。
### 启动 HTTP 服务器
直接运行 claude-team HTTP 服务器：
```bash # From the claude-team directory uv run python -m claude_team_mcp --http --port 8766
# Or specify the directory explicitly uv run --directory /path/to/claude-team python -m claude_team_mcp --http --port 8766 ```
要在登录时自动启动，请使用 launchd（请参阅下面的“launchd 自动启动”部分）。
### mcporter.json 配置
HTTP 服务器运行后，配置 mcporter 连接到它。创建 `~/.mcporter/mcporter.json`：
```json { "mcpServers": { "claude-team": { "transport": "streamable-http", "url": "http://127.0.0.1:8766/mcp", "lifecycle": "keep-alive" } } } ```
### HTTP 模式的优势
- **持久状态**：Worker 注册表在 CLI 调用之间仍然存在 - **更快的响应**：每次调用无需启动 Python 环境 - **外部访问**：可由 cron 作业、脚本或其他工具访问 - **会话恢复**：即使协调器断开连接，服务器也会跟踪会话
### 从 Claude Code 连接
更新你的 `.mcp.json` 以使用 HTTP 传输：
```json { "mcpServers": { "claude-team": { "transport": "streamable-http", "url": "http://127.0.0.1:8766/mcp" } } } ```
## launchd 自动启动
要在登录时自动启动 claude-team 服务器，请使用捆绑的设置脚本。
### 快速设置
从技能的 assets 目录运行设置脚本：
```bash # From the skill directory ./assets/setup.sh
# Or specify a custom claude-team location 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 会话类型）。
### 管理服务
```bash # Stop the service launchctl unload ~/Library/LaunchAgents/com.claude-team.plist
# Restart (re-run setup) ./assets/setup.sh
# Check if running launchctl list | grep claude-team
# View logs tail -f ~/.claude-team/logs/stdout.log tail -f ~/.claude-team/logs/stderr.log ```
### launchd 故障排除
```bash # Check for load errors launchctl print gui/$UID/com.claude-team
# Force restart launchctl kickstart -k gui/$UID/com.claude-team
# Remove and reload (if plist changed) launchctl bootout gui/$UID/com.claude-team launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.claude-team.plist ```
## Cron 集成
为了后台监控和通知，claude-team 支持基于 cron 的 worker 跟踪。
### Worker 跟踪文件
Claude-team 将 worker 状态写入 `~/.claude-team/memory/worker-tracking.json`：
```json { "workers": { "Groucho": { "session_id": "3962c5c4", "bead": "cp-123", "annotation": "Fix auth bug", "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": "Add API routes", "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` 创建监控脚本：
```bash #!/bin/bash # Check for completed workers and send notifications
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}"
# Exit if tracking file doesn't exist [ -f "$TRACKING_FILE" ] || exit 0
# Initialize notified file if needed [ -f "$NOTIFIED_FILE" ] || echo '{"notified":[]}' > "$NOTIFIED_FILE"
# Find idle workers that haven't been notified IDLE_WORKERS=$(jq -r ' .workers | to_entries[] | select(.value.status == "idle") | .key ' "$TRACKING_FILE")
for worker in $IDLE_WORKERS; do # Check if already notified ALREADY_NOTIFIED=$(jq -r --arg w "$worker" '.notified | index($w) != null' "$NOTIFIED_FILE")
if [ "$ALREADY_NOTIFIED" = "false" ]; then # Get worker details 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")
# Send Telegram notification MESSAGE="🤖 Worker *${worker}* completed 📋 Bead: \`${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
# Mark as notified jq --arg w "$worker" '.notified += [$w]' "$NOTIFIED_FILE" > "${NOTIFIED_FILE}.tmp" mv "${NOTIFIED_FILE}.tmp" "$NOTIFIED_FILE" fi done ```
使其可执行：
```bash chmod +x ~/.claude-team/scripts/check-workers.sh ```
### Crontab 条目
添加到 crontab（`crontab -e`）：
```cron # Check claude-team workers every 2 minutes */2 * * * * TELEGRAM_BOT_TOKEN="your-bot-token" TELEGRAM_CHAT_ID="your-chat-id" ~/.claude-team/scripts/check-workers.sh ```
### 环境设置
在你的 shell 配置文件（`~/.zshrc`）中设置 Telegram 凭证：
```bash export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz" export TELEGRAM_CHAT_ID="-1001234567890" ```
### 替代方案：使用 clawdbot 进行通知
如果你配置了 clawdbot，可以通过它发送通知：
```bash # In check-workers.sh, replace the curl command with: clawdbot send --to "$TELEGRAM_CHAT_ID" --message "$MESSAGE" --provider telegram ```
### 清除通知状态
启动一批新的 worker 时，清除已通知列表：
```bash echo '{"notified":[]}' > ~/.claude-team/memory/notified-workers.json ```