Claude Team

Maniple MCP服务器

一种MCP服务器，允许一个Claude Code会话通过终端后端（tmux或iTerm2）生成和管理其他Claude Code（或Codex）会话的团队。

介绍

maniple 是一个MCP服务器和一组斜线命令，用于允许Claude Code编排其他Claude Code或Codex会话的“团队”。它使用终端后端（tmux或iTerm2）生成新的终端会话，并在其中运行Claude Code或Codex。

为什么？

• 平行度： 许多开发任务可以在逻辑上并行化，但对于注意力有限的人来说，管理这种并行性是困难的。与此同时，克劳德在这方面非常有效。
• 上下文管理： 将实现卸载给worker为实现代理提供了一个新的上下文窗口（更智能），并使管理者的上下文不受实现细节的影响。
• 背景工作： 有时你想让Claude Code去研究一些东西或回答一个问题，而不会阻塞工作的主线。
• 可见性： maniple 产生真正的克劳德法典或法典会议。你可以观察他们，打断他们，控制他们，或者把他们关起来。

但是， *为什么不直接使用Claude Code子代理*你问？它们是不透明的——它们会离开并做事情，而你，作为用户，无法有效地监控他们的工作、打断他们或继续与他们交谈。使用完整的Claude Code会话可以避免这个问题。

终端后端

maniple 支持两个终端后端：

后端选择顺序：

1. MANIPLE_TERMINAL_BACKEND 环境变量(tmux 或 iterm)
2. 配置文件设置(terminal.backend)
3. 自动检测：如果 TMUX env-var已设置，请使用tmux；否则iTerm2

Git工作树：每个Worker的独立分支

一个关键特征是 maniple 是 git工作台支持.产卵时，用 use_worktree: true （默认值），每个worker得到：

• 自己的工作目录 -一个git工作台 {repo}/.worktrees/{name}/
• 自己的分支机构 -从当前HEAD自动创建
• 共享存储库历史记录 -所有工作树共享相同的 .git 数据库，因此提交在工作人员中立即可见

工作树命名取决于如何生成workers：

• 带有问题ID： {repo}/.worktrees/{issue_id}-{badge}/
• 没有： {repo}/.worktrees/{worker-name}-{uuid}-{badge}/

这 .worktrees 目录会自动添加到 .gitignore.

食品法典支持

工人可以运行Claude Code或OpenAI Codex。集 agent_type: "codex" 在worker配置中（或在配置文件中设置默认值）生成Codex workers而不是Claude Code workers。

特性

• Spawn工人：使用多窗格布局创建Claude Code或Codex会话
• 终端后端：tmux（跨平台）和iTerm2（macOS）
• Git工作树：将每个worker隔离在自己的分支和工作目录中
• 发送消息：向受管员工注入提示（单个或广播）
• 读取日志：从worker JSONL文件中检索对话历史记录
• 监视状态：检查工人是否空闲、正在处理或等待输入
• 怠速检测：等待工人使用停止钩标记完成
• 事件轮询：跟踪工作人员生命周期事件（开始、完成、卡住）
• 视觉识别：每个工人都有一个独特的标签颜色和主题名称（马克思兄弟、披头士等）
• 会话恢复：在MCP服务器重新启动后发现并采用孤立会话
• HTTP模式：作为具有流式http传输的持久服务运行
• 配置文件：集中配置 ~/.maniple/config.json

需求

• Python 3.11+
• uv 包管理器
• tmux后端：tmux已安装（macOS或Linux）
• iTerm2后端：启用iTerm2和Python API的macOS（首选项>常规>魔术>启用Python API）
• 食品法典工作人员 （可选）：已安装OpenAI Codex CLI

安装

作为Claude代码插件（推荐）

# Add the Martian Engineering marketplace
/plugin marketplace add Martian-Engineering/maniple

# Install the plugin
/plugin install maniple@martian-engineering

这会自动配置MCP服务器，无需手动设置。

来自PyPI

uvx --from maniple-mcp@latest maniple

来源

git clone https://github.com/Martian-Engineering/maniple.git
cd maniple
uv sync

Claude代码的配置

添加到您的Claude Code MCP设置中。您可以在以下位置进行配置：

• 全球: ~/.claude/settings.json
• 项目: .claude/settings.json 在您的项目目录中

使用PyPI包

{
  "mcpServers": {
    "maniple": {
      "command": "uvx",
      "args": ["--from", "maniple-mcp@latest", "maniple"]
    }
  }
}

使用本地克隆

{
  "mcpServers": {
    "maniple": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/maniple", "python", "-m", "maniple_mcp"]
    }
  }
}

具有自动项目路径的项目级别

适用于项目范围 .mcp.json 文件，使用 MANIPLE_PROJECT_DIR 因此workers继承了项目路径：

{
  "mcpServers": {
    "maniple": {
      "command": "uvx",
      "args": ["--from", "maniple-mcp@latest", "maniple"],
      "env": { "MANIPLE_PROJECT_DIR": "${PWD}" }
    }
  }
}

添加配置后，重新启动Claude Code使其生效。

配置文件

maniple 从以下位置读取配置 ~/.maniple/config.json.使用CLI进行管理：

maniple config init          # Create default config
maniple config init --force  # Overwrite existing config
maniple config show          # Show effective config (file + env overrides)
maniple config get      # Get value by dotted path (e.g. defaults.layout)
maniple config set    # Set and persist a value

迁移说明（来自 claude-team)

• 配置目录： ~/.claude-team/ 自动迁移到 ~/.maniple/ 第一次跑步。
• 环境变量： MANIPLE_* 优先； CLAUDE_TEAM_* 支持作为回退，并可能向stderr发出弃用警告。

配置架构

{
  "version": 1,
  "commands": {
    "claude": null,
    "codex": null
  },
  "defaults": {
    "agent_type": "claude",
    "skip_permissions": false,
    "use_worktree": true,
    "layout": "auto"
  },
  "terminal": {
    "backend": null
  },
  "events": {
    "max_size_mb": 1,
    "recent_hours": 24
  },
  "issue_tracker": {
    "override": null
  }
}

环境变量

MCP工具

工人管理

沟通

监控

公用事业

工人身份

工人可以通过三个标识符中的任何一个引用：

• 内部ID：短十六进制字符串（例如。， 3962c5c4)
• 终端标识符：前缀终端会话ID（例如。， iterm:UUID 或 tmux:%1)
• 工人姓名：人类友好名称（例如。， Groucho, Aragorn)

所有工具都接受这些格式中的任何一种。

工具详细信息

spawn_workers

WorkerConfig fields:
  project_path: str         - Required. Explicit path or "auto" (uses MANIPLE_PROJECT_DIR)
  agent_type: str           - "claude" (default) or "codex"
  name: str                 - Optional worker name override (auto-picked from themed sets if omitted)
  badge: str                - Task description (shown in badge, used in branch names)
  issue_id: str             - Issue tracker ID (for badge, branch naming, and workflow instructions)
  prompt: str               - Additional instructions (combined with standard worker prompt)
  skip_permissions: bool    - Start with --dangerously-skip-permissions
  use_worktree: bool        - Create isolated git worktree (default: true)
  worktree: WorktreeConfig  - Optional worktree settings:
                              branch: Explicit branch name (auto-generated if omitted)
                              base: Ref/branch to branch FROM (default: HEAD). Set this
                                    when subtask workers need a feature branch's commits
                                    (e.g. {"base": "epic-id/feature-branch"})

Top-level arguments:
  workers: list[WorkerConfig]  - 1-4 worker configurations
  layout: str                  - "auto" (reuse windows) or "new" (fresh window)

Returns:
  sessions, layout, count, coordinator_guidance

工人分配由以下因素决定 issue_id 和 prompt:

• 仅限issue_id：工作人员遵循问题跟踪工作流（标记in_progress、实施、关闭、提交）
• issue_id+提示：问题跟踪器工作流程以及其他自定义说明
• 仅提示：没有问题跟踪的自定义任务
• 两者都不：Worker生成空闲状态，等待消息

消息_员工

Arguments:
  session_ids: list[str]   - Worker IDs to message (accepts any identifier format)
  message: str             - The prompt to send
  wait_mode: str           - "none" (default), "any", or "all"
  timeout: float           - Max seconds to wait (default: 600)

Returns:
  success, session_ids, results, [idle_session_ids, all_idle, timed_out]

服务员

Arguments:
  session_ids: list[str]   - Worker IDs to wait on
  mode: str                - "all" (default) or "any"
  timeout: float           - Max seconds to wait (default: 600)
  poll_interval: float     - Seconds between checks (default: 2)

Returns:
  session_ids, idle_session_ids, all_idle, waiting_on, mode, waited_seconds, timed_out

poll_worker_changes

Arguments:
  since: str                    - ISO timestamp to filter events from (or null for latest)
  stale_threshold_minutes: int  - Minutes without activity before marking stuck (default: 20)
  include_snapshots: bool       - Include periodic snapshot events (default: false)

Returns:
  events, summary (started/completed/stuck), active_count, idle_count, poll_ts

HTTP服务器模式

跑 maniple 作为持久HTTP服务而不是stdio：

maniple --http              # Default port 8766
maniple --http --port 9000  # Custom port

HTTP模式启用：

• 可流式HTTP传输 用于MCP通信
• 工人投票员 定期快照工作进程状态并发出生命周期事件
• MCP资源 对于只读会话访问：

- sessions://list -列出所有托管会话 - sessions://{session_id}/status -详细的会话状态 - sessions://{session_id}/screen -终端屏幕内容

斜杠命令

为常见工作流安装斜线命令：

make install-commands

问题跟踪支持

maniple 支持两种鹅卵石(pb)和珠子(bd --no-db). 跟踪器由项目根目录中的标记目录自动检测：

• .pebbles ->鹅卵石
• .beads ->珠子

如果两个标记都存在，则默认选择“鹅卵石”。这可以在配置文件中用以下命令覆盖 issue_tracker.override。工作人员提示和协调指导使用检测到的跟踪器命令。

使用模式

基础：出生和消息

在Claude Code会话中，生成workers并向他们发送任务：

"Spawn two workers for frontend and backend work"
-> Uses spawn_workers with two WorkerConfigs pointing at different project paths
-> Returns workers named e.g. "Simon" and "Garfunkel"

"Send Simon the message: Review the React components"
-> Uses message_workers with session_ids=["Simon"]

"Check on Garfunkel's progress"
-> Uses examine_worker with session_id="Garfunkel"

与Worktrees并行工作

在孤立的分支中培养工人以进行并行开发：

"Spawn three workers with worktrees to work on different features"
-> Uses spawn_workers with use_worktree=true (default)
-> Creates worktrees at {repo}/.worktrees/
-> Each worker gets their own branch

"Message all workers with their tasks, then wait for completion"
-> Uses message_workers with wait_mode="all"

"Create PRs for each worker's branch"
-> Uses /pr-worker for each completed worker

问题跟踪器集成

为结构化工作流分配工作人员发布跟踪项：

"Spawn a worker for issue cic-123"
-> spawn_workers with issue_id="cic-123", badge="Fix auth bug"
-> Worker automatically marks issue in_progress, implements, closes, and commits

"Spawn workers for all ready issues"
-> Check `bd ready` or `pb ready` for available work
-> Spawn one worker per issue with issue_id assignments

协调工作流程

使用经理在员工之间进行协调：

"Spawn a backend worker to create a new API endpoint"
-> Wait for completion with wait_idle_workers

"Now spawn a frontend worker and tell it about the new endpoint"
-> Pass context from read_worker_logs of the backend worker

"Spawn a test worker to write integration tests"
-> Coordinate based on both previous workers' output

建筑

┌──────────────────────────────────────────────────────────────────┐
│                Manager Claude Code Session                       │
│                (has maniple MCP server)                          │
├──────────────────────────────────────────────────────────────────┤
│                         MCP Tools                                │
│  spawn_workers | message_workers | wait_idle_workers | etc.      │
└───────────────────────────┬──────────────────────────────────────┘
                            │
               ┌────────────┼────────────┐
               ▼            ▼            ▼
         ┌──────────┐ ┌──────────┐ ┌──────────┐
         │ Groucho  │ │ Harpo    │ │ Chico    │
         │ (tmux)   │ │ (tmux)   │ │ (tmux)   │
         │          │ │          │ │          │
         │  Claude  │ │  Claude  │ │  Codex   │
         │   Code   │ │   Code   │ │          │
         │          │ │          │ │          │
         │ worktree │ │ worktree │ │ worktree │
         │ .worktrees/ │ .worktrees/ │ .worktrees/ │
         └──────────┘ └──────────┘ └──────────┘

经理认为：

• 会话注册表：将工作人员ID/姓名映射到终端会话
• 终端后端：与tmux或iTerm2的持久连接用于终端控制
• JSONL监控：读取Claude/Codex会话文件以检测会话状态和空闲状态
• 工作树跟踪：管理隔离工作分支的git工作树
• 事件日志：记录用于轮询和诊断的工作人员生命周期事件

发展

# Sync dependencies (with dev tools)
uv sync --group dev

# Run tests
uv run pytest

# Run the server directly (for debugging)
uv run python -m maniple_mcp

# Run in HTTP mode
uv run python -m maniple_mcp --http

# Install slash commands
make install-commands

故障排除

tmux后端

“找不到tmux”

• 安装tmux： brew install tmux （macOS）或 apt install tmux （Linux）
• 确保tmux在您的PATH中

重启后未检测到工人

• 使用 discover_workers 查找孤立会话
• 使用 adopt_worker 重新注册
• 会话通过写入JSONL文件的标记进行匹配

iTerm2后端

“无法连接到iTerm2”

• 确保iTerm2正在运行
• 启用：iTerm2>首选项>常规>魔术>启用Python API

将军

“未找到会话”

• 工人可能已被外部关闭
• 使用 list_workers 看到活跃的工人
• 工人可以通过ID、终端ID或姓名进行引用

“未找到JSONL会话文件”

• Claude Code可能仍在启动中
• 请等待几秒钟，然后重试
• 检查Claude Code是否确实在工作窗格中运行

工作树问题

• 使用 list_worktrees 查看存储库的工作树
• 孤立的工作树可以用 list_worktrees + remove_orphans=true
• 工作树存放在 {repo}/.worktrees/

升级

在新版本发布到PyPI后，您可能需要强制刷新缓存的版本：

uv cache clean --force
uv tool install --force --refresh maniple

这是必要的，因为 uvx 积极缓存工具环境。

许可证

麻省理工学院