让 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 将问题推送到另一个面板并读取回复。目标面板由运行中的进程自动检测——你不需要标记标签页，也不需要针对每个项目进行任何预配置。
现有的多智能体框架分为两类：
重量级：有守护进程、每个项目都有配置文件、不透明的会话状态。在凌晨两点出问题且找不到原因时，这会非常糟糕。
单进程：一个模型在内部编排子智能体，用户只能看到最终答案。
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/），你可以自行核对数据。
git clone https://github.com/jonghklee/teammate-mcp.git
cd teammate-mcp
uv venv
uv pip install -e .# 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你有两个选择：
选项 A — 让 bin/team 为你打开一个新的 iTerm 窗口：
./bin/team选项 B — 使用你已经打开的任何 iTerm 窗口。只需在一个面板中运行 claude，在另一个面板中运行 codex。teammate-mcp 会通过进程名称找到它们；无需标签。
将 templates/AGENTS.md 放入你的项目根目录。Claude Code 和 Codex 都会自动读取它（这是它们都遵循的约定）。该文件告诉它们如何以及何时互相调用。
在 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）调用：
生成一个唯一标记，将消息加入磁盘队列（pending/ → inflight/ 原子重命名）。
定位目标面板：
优先使用 TEAMMATE_<UPPER>_SESSION_ID 环境变量覆盖
否则枚举所有活动进程（ps 风格），找到任何 claude 或 codex 进程，读取其 TERM_SESSION_ID 环境变量，并将其与 iTerm 的会话列表进行匹配。这适用于 tmux、登录 shell 和 pyenv 包装器 —— 只要继承了环境变量即可。
回退到 jobName / commandLine 匹配，并优先考虑当前工作目录 (cwd)。
async_send_text 发送提示词 + 一个要求用标记终止回复的请求。
轮询 async_get_screen_contents 以查找标记。由于我们输入的提示词包含标记文本（它会在面板中回显），服务器要求标记出现两次后才认为回复完成。
截取两次标记出现之间的答案，记录 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”即可。
Ask the Claude pane a question and return its answer.
Use this from Codex when you want Claude's plan, design feedback, or a sanity check.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It only states it returns an answer, but does not disclose potential side effects, timeout behavior, or whether it is a read-only operation. The agent lacks critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only two short sentences, no redundant information, and the primary action is front-loaded. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters and an output schema, but the description lacks detail on the output format and usage constraints. An agent can infer basic usage but may miss nuances like timeout meaning or question style expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds no information about the 'question' or 'timeout' parameters beyond what the schema provides. For a tool with 2 parameters and no enum constraints, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Ask' and the resource 'Claude pane', specifying that it returns an answer. The sibling tool 'ask_codex' helps differentiate, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool for 'plan, design feedback, or a sanity check' from Codex, providing clear context. However, it does not mention when to avoid using this tool in favor of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the Codex pane a question and return its answer.
Use this from Claude when you want Codex's opinion, a code review, or to delegate execution to it.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks behavioral details such as side effects, authentication requirements, rate limits, or any constraints. Merely states it returns an answer without elaboration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. First sentence is clear; second adds usage guidance. Could be slightly more efficient, but overall well-structured for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details on return value format despite having an output schema. No information on how Codex processes the question or what happens with the timeout. Minimal guidance for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in schema. The description does not explain the 'question' or 'timeout' parameters at all, adding zero value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'ask' and the resource 'Codex pane', with explicit mention of returning an answer. Distinguishes from sibling 'ask_claude' by naming Codex specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this from Claude when you want Codex's opinion, a code review, or to delegate execution to it', providing clear context and implicitly contrasting with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push a message to both panes without waiting for a reply.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses the key behavior of not waiting for a reply, but omits other behavioral traits like side effects, required permissions, or whether the message is stored. This is adequate for a simple tool but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It is appropriately sized and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description is minimally complete. It covers the core action and behavioral note, but does not explain 'both panes' or provide any usage context. It meets the minimum viability for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It says 'message' but adds no detail beyond the schema's type string. It does not explain format, constraints, or expected values, which is insufficient for a parameter with no description in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool pushes a message to both panes without waiting for a reply, using a specific verb and resource. This distinguishes it from sibling tools like ask_claude and ask_codex, which likely expect replies, and queue_status for status checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives. It does not mention when not to use it or compare it to sibling tools, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return queue counts + recent completions (debugging).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description clearly indicates it is a non-destructive read (returning counts and completions). There is no behavior beyond what is described, and no contradictions. A slight deduction for not explicitly stating read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence that immediately states the tool's purpose and context. No fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description sufficiently describes the tool's output. It could be considered complete for a simple status check, though mentioning any authentication or availability requirements would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 params, 100% coverage). The description adds value by specifying the return content (queue counts + recent completions). Baseline 4 is appropriate since the schema carries no burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns queue counts and recent completions, with 'debugging' context. It identifies the specific resource (queue status) and verb (return). It is well distinguished from siblings like ask_claude, ask_codex, and broadcast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for debugging via the parenthetical '(debugging)'. It does not explicitly state when to use vs. alternatives or when not to use, but the siblings are sufficiently different, so the guidance is adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0ask_claudeask_codexbroadcastqueue_statusScored across 4 tools
Each tool has a distinct purpose: ask_claude and ask_codex target specific panes, broadcast sends to both without waiting, and queue_status provides debugging info. No overlap.
All tool names use lowercase with underscores and follow a consistent verb_noun pattern (ask_claude, ask_codex, queue_status) or are a clear verb (broadcast).
4 tools is well-scoped for the server's purpose of inter-pane communication, covering questioning each pane, broadcasting, and status monitoring.
Core workflows are covered, but a minor gap exists: there is no tool to send a one-way message to a specific pane without expecting a reply (only broadcast to both).
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Shared memory for AI tools: save once, recall word for word from Claude, ChatGPT, Codex or Gemini.
