teammate-mcp

让 Claude Code 和 OpenAI Codex 通过你的 iTerm 面板相互提问。 无需守护进程。无需为每个项目手动编辑 .config 文件。 只需打开两个面板，它们就能对话。

┌──────────── iTerm window ─────────────┐
│ claude  (left)        codex  (right)  │
│ ───────────────────   ─────────────── │
│ > implement quoter    > [teammate-mcp │
│   I'll ask Codex...     ASK ... what  │
│   ⏺ Codex answered:     is 2+2?]      │
│      4                  • 4           │
└───────────────────────────────────────┘

teammate-mcp 是一个微型 MCP 服务器，它为加载它的 CLI 提供两个工具：

• mcp__teammate__ask_codex(question, timeout) — 从 Claude 调用

• mcp__teammate__ask_claude(question, timeout) — 从 Codex 调用

该服务器使用 iTerm2 Python API 将问题推送到另一个面板并读取回复。目标面板由运行中的进程自动检测——你不需要标记标签页，也不需要针对每个项目进行任何预配置。

为什么？

现有的多智能体框架分为两类：

1. 重量级：有守护进程、每个项目都有配置文件、不透明的会话状态。在凌晨两点出问题且找不到原因时，这会非常糟糕。

2. 单进程：一个模型在内部编排子智能体，用户只能看到最终答案。

teammate-mcp 旨在提供第三种选择：两个智能体在你的终端中并排可见地运行，你可以实时阅读两者的对话记录，唯一的“基础设施”就是几百行用于推送文本和读取屏幕的 Python 代码。

Related MCP server: claude-mux-iterm

已验证的双向往返

在 macOS 14、iTerm 3.6.8、Claude Code 2.1.119 + Opus 4.7、Codex 0.125.0 开发期间实时捕获：

{"event":"ask.enqueue","id":"…c5d085","from_":"claude","to":"codex","len":49}
{"event":"ask.send",   "id":"…c5d085","to":"codex","session_id":"7E39032F-…"}
{"event":"ask.complete","id":"…c5d085","answer_len":3}

对于“二加二等于几？仅用数字回答”这一提示词，ask.send → ask.complete 的间隔为 3.0 秒 —— 其中大部分时间是 Codex 的思考时间，而不是桥接延迟。五次连续运行均在 1.5 到 4.5 秒内完成了闭环。

仓库中包含了六份独立的计时报告（位于 tests/results/），你可以自行核对数据。

快速开始

1. 安装

git clone https://github.com/jonghklee/teammate-mcp.git
cd teammate-mcp
uv venv
uv pip install -e .

2. 向两个 CLI 注册服务器

# Claude Code
claude mcp add teammate -s user -- $PWD/.venv/bin/teammate-mcp serve

# Codex
codex  mcp add teammate           -- $PWD/.venv/bin/teammate-mcp serve

3. 打开面板

你有两个选择：

选项 A — 让 bin/team 为你打开一个新的 iTerm 窗口：

./bin/team

选项 B — 使用你已经打开的任何 iTerm 窗口。只需在一个面板中运行 claude，在另一个面板中运行 codex。teammate-mcp 会通过进程名称找到它们；无需标签。

4. （一次性）向智能体提供操作规则

将 templates/AGENTS.md 放入你的项目根目录。Claude Code 和 Codex 都会自动读取它（这是它们都遵循的约定）。该文件告诉它们如何以及何时互相调用。

5. 尝试一下

在 Claude 面板中：

Ask Codex what timezone library it prefers in Python and tell me what
it said.

你会看到 Claude 调用 mcp__teammate__ask_codex，问题出现在右侧面板，Codex 做出响应，然后 Claude 转发答案。

工作原理

┌──────────────────────────────────────────────────────┐
│  Claude pane              Codex pane                  │
│  ─────────────            ─────────────               │
│   user prompt              [teammate-mcp ASK …]       │
│        │ tool call              ▲                     │
│        ▼                        │ async_send_text     │
│  ┌──────────────┐               │                     │
│  │ teammate-mcp │  ─────────────┘                     │
│  │  (FastMCP)   │  ◄────── async_get_screen_contents  │
│  └──────────────┘                                     │
│        │                                              │
│        └─► returns extracted answer to Claude         │
└──────────────────────────────────────────────────────┘

对于每个 ask_codex（或 ask_claude）调用：

1. 生成一个唯一标记，将消息加入磁盘队列（pending/ → inflight/ 原子重命名）。

2. 定位目标面板：

   • 优先使用 TEAMMATE_<UPPER>_SESSION_ID 环境变量覆盖

   • 否则枚举所有活动进程（ps 风格），找到任何 claude 或 codex 进程，读取其 TERM_SESSION_ID 环境变量，并将其与 iTerm 的会话列表进行匹配。这适用于 tmux、登录 shell 和 pyenv 包装器 —— 只要继承了环境变量即可。

   • 回退到 jobName / commandLine 匹配，并优先考虑当前工作目录 (cwd)。

3. async_send_text 发送提示词 + 一个要求用标记终止回复的请求。

4. 轮询 async_get_screen_contents 以查找标记。由于我们输入的提示词包含标记文本（它会在面板中回显），服务器要求标记出现两次后才认为回复完成。

5. 截取两次标记出现之间的答案，记录 ask.complete，并将答案返回给调用者。

“无需配置”的真正含义

只有一件事需要配置（一次）：上述第 2 步中的 MCP 注册。之后，任何带有 claude+codex 面板的 iTerm 窗口都可以直接工作 —— 包括在你安装 teammate-mcp 之前就已经打开的窗口。

你永远不需要编写 .teammate.toml，不需要运行 teammate start，也不需要记住哪个会话 ID 是哪个。

测试

uv pip install -e ".[dev]"
pytest                              # 18 unit + integration tests
python scripts/auto_demo.py         # full end-to-end demo (spawns iTerm)

单元测试涵盖了队列、ANSI/标记处理、服务器模块导入以及带有模拟的 iTerm 会话发现逻辑。端到端演示会打开一个真实的 iTerm 窗口并执行 Claude → Codex → Claude 的往返过程；它要求两个 CLI 都已登录，并会产生正常的 API 费用。

每次运行的计时报告都会写入 tests/results/*.jsonl。提交到仓库中的报告是真实的，而非合成的。

故障排除

“iTerm Python API is not enabled” — 设置 → 通用 → Magic → “Enable Python API” ✓。teammate-mcp 首次连接时，iTerm 也会提示权限请求；点击 Allow。

“asyncio.run() cannot be called from a running event loop” — 你使用的 teammate-mcp 版本低于 0.1.0。请拉取 main 分支；工具现在已声明为 async。

“Tool returned an answer that's just my own prompt echo” — 提示词目标面板运行了错误的 CLI（例如，查找选中了运行相同进程的兄弟面板）。请显式固定面板：

export TEAMMATE_CLAUDE_SESSION_ID=<unique id from iTerm>
export TEAMMATE_CODEX_SESSION_ID=<unique id from iTerm>

（你可以从 Window menu → Window Settings → Identifier 或通过 AppleScript 读取每个面板的 unique id。）

“Marker not detected within timeout” — 另一端的智能体忘记发出 <<DONE_…>>。在你的 AGENTS.md 中添加明确的提醒。捆绑的模板已经包含了这一点。

许可证

MIT — 参见 LICENSE。

致谢

本项目基于 2026 年关于 Claude Code 和 Codex 如何运行的公开研究讨论而形成：

• Anthropic 的 Plan-Generate-Verify 和 Initializer + Coding Agent 框架论文 (Rajasekaran 2026-03; Justin Young 2025-11)。

• IndyDevDan 的 claude-code-hooks-mastery 用于可观测性模式。

• OthmanAdi 的 planning-with-files 用于“结构化文件桥接会话，而非聊天记录”的理念。

• Boris Cherny 在其 How I use Claude Code 帖子中的“验证循环”规则。

• Geoffrey Huntley 的 Ralph Wiggum 循环，用于“每次轮次提供新鲜上下文”的直觉。

其实现归功于 iTerm2 文档 https://iterm2.com/python-api/ 中的 iTerm Python API 模式。

韩语摘要

这是一个微型 MCP 服务器，无需像 CCB 那样的预配置，即可让 claude / codex 相互提问。

• 只需在 iTerm 的两个面板中分别运行 claude 和 codex 即可。没有标签、没有配置、没有守护进程。

• 通过 iTerm Python API 自动检测对方面板（匹配运行进程 + 环境变量 TERM_SESSION_ID）——即使在 tmux 中运行也能工作。

• 消息通过 push 发送，回复通过轮询接收，所有往返记录都会保存在 ~/.teammate-mcp/logs/<日期>.jsonl 中。

• 实测往返时间：以 2 + 2 = 4 的问题为例，send → complete 为 3.0 秒（大部分是 Codex 的思考时间）。

安装请参考上述英文 Quick start 1~3 步，使用方法只需像平时一样让 Claude “问问 Codex”即可。