claude-team

用途

Claude Team 是一个 MCP 服务器，让你通过 iTerm2 生成和管理一组 Claude Code 会话（称为 worker）。每个 worker 拥有自己的终端窗格、可选的 git worktree，并可以被分配 beads 议题。它主要用于把编码任务并行分发给多个智能体，同时保持协调者（coordinator）的上下文干净。

主要能力

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

核心工具（通过 mcporter 调用）：

• spawn_workers：创建新的 Claude Code worker 会话，支持 project_path、bead、annotation、prompt、use_worktree、skip_permissions、name 等配置字段，以及 layout（auto/new）布局选项。
• list_workers：查看所有受管理的 worker，可按状态过滤（spawning、ready、busy、closed）。
• message_workers：向一个或多个 worker 发送消息，wait_mode 支持 none、any、all。
• check_idle_workers / wait_idle_workers：检查或等待 worker 完成。
• read_worker_logs：获取对话历史。
• examine_worker：获取详细状态，包括对话统计。
• close_workers：任务完成后终止 worker。
• bd_help：beads 命令的快速参考。

Worker 可通过内部 ID（短十六进制字符串）、终端 ID（iterm:UUID 格式）或 worker 名称（如 Groucho、Aragorn）引用。

使用方式

前置条件：macOS 与 iTerm2（需启用 Python API：Preferences → General → Magic → Enable Python API），并在 ~/.claude.json 中配置 claude-team MCP 服务器。

所有工具通过 mcporter call claude-team.<tool> 调用，例如：

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

分配 beads 议题的工作流：生成带 bead 的 worker 后，worker 会自动创建以 bead 命名的分支 worktree、运行 bd show 理解任务、标记议题为 in_progress、实现工作、关闭议题并以议题引用提交；随后可监控进度、关闭并合并。

并行分发工作流：一次生成多个 worker 处理并行任务，用 wait_idle_workers 等待全部完成，再审查并关闭。

HTTP 模式：claude-team 可作为 HTTP 服务器常驻运行，保持持久状态、避免冷启动。启动命令：

uv run python -m claude_team_mcp --http --port 8766

并在 ~/.mcporter/mcporter.json 中配置 streamable-http 传输指向 http://127.0.0.1:8766/mcp。也可在 .mcp.json 中配置 Claude Code 使用 HTTP 传输。

launchd 自动启动：运行 ./assets/setup.sh 可生成并安装 launchd plist 到 ~/Library/LaunchAgents/com.claude-team.plist，实现登录时自动启动。

Cron 集成：claude-team 将 worker 状态写入 ~/.claude-team/memory/worker-tracking.json，可配合 cron 脚本监控完成情况并发送通知（如 Telegram）。

适用场景

• 需要将多个编码任务并行分发给多个 Claude Code 会话。
• 希望每个任务在隔离的 git worktree 分支中进行，便于审查与合并。
• 需要可视化监控、中断或接管智能体会话。
• 需要常驻服务器或后台监控通知的团队协作场景。

限制与注意事项

• 重要规则：绝不直接修改代码，代码变更始终通过生成 worker 完成。
• 需要 macOS 与 iTerm2，并启用 Python API。
• worker 需要 skip_permissions: true 才能写入文件。
• 带 worktree 的 worker 提交到临时分支，关闭后需审查提交、合并或 cherry-pick 到持久分支，并删除该分支。
• 完成后应始终关闭 worker 以清理 worktree。
• 其他平台支持情况、收费与价格信息暂未提供。