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는 이를 로드하는 CLI에 두 가지 도구를 제공하는 작은 MCP 서버입니다:
mcp__teammate__ask_codex(question, timeout) — Claude에서 호출
mcp__teammate__ask_claude(question, timeout) — Codex에서 호출
이 서버는 iTerm2 Python API를 사용하여 질문을 다른 페인으로 보내고 응답을 읽어옵니다. 대상 페인은 실행 중인 프로세스에 의해 자동으로 감지되므로, 탭에 라벨을 붙이거나 프로젝트별로 미리 설정할 필요가 없습니다.
기존의 멀티 에이전트 도구들은 크게 두 가지 유형으로 나뉩니다:
헤비급: 데몬, 프로젝트별 설정 파일, 불투명한 세션 상태. 새벽 2시에 문제가 발생하면 원인을 알 수 없어 매우 불편합니다.
단일 프로세스: 하나의 모델이 내부적으로 하위 에이전트를 조정하므로, 사용자는 최종 결과만 볼 수 있습니다.
teammate-mcp는 세 번째 옵션을 지향합니다. 두 에이전트가 터미널에서 나란히 실행되는 것을 눈으로 확인할 수 있고, 실시간으로 두 대화 내용을 모두 읽을 수 있으며, 유일한 "인프라"는 텍스트를 보내고 화면을 읽는 수백 줄의 파이썬 코드뿐입니다.
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}"2 더하기 2는 무엇인가요? 숫자만으로 답하세요"라는 프롬프트에 대해 ask.send → ask.complete 간격은 3.0초였습니다. 이 시간의 대부분은 브릿지 통신이 아닌 Codex의 사고 시간입니다. 연속 5회 실행 모두 1.5~4.5초 내에 루프가 완료되었습니다.
tests/results/에 캡처된 6개의 독립적인 타이밍 보고서가 저장소에 포함되어 있어 직접 수치를 검증할 수 있습니다.
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, 로그인 셸, pyenv 래퍼를 통해서도 작동합니다 — 환경 변수가 상속되는 곳이라면 어디서든 가능합니다.
마지막으로 현재 작업 디렉토리(cwd)를 우선순위로 하여 jobName / commandLine 매칭을 수행합니다.
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" — 0.1.0 이전 버전의 teammate-mcp를 사용 중입니다. main 브랜치를 pull 하세요. 도구들이 이제 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>(각 페인의 unique id는 Window menu → Window Settings → Identifier 또는 AppleScript를 통해 확인할 수 있습니다.)
"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 루프 ("턴마다 새로운 컨텍스트"라는 직관).
구현에 사용된 iTerm Python API 패턴은 https://iterm2.com/python-api/의 iTerm2 문서를 참고했습니다.
CCB 같은 사전 설정 없이 claude / codex가 서로에게 질문할 수 있게 해주는 작은 MCP 서버입니다.
iTerm 두 페인에 그냥 claude와 codex를 띄우기만 하면 됩니다. 라벨도, config도, daemon도 없습니다.
iTerm Python API로 상대 페인을 자동 탐지(실행 프로세스 + 환경변수 TERM_SESSION_ID 매칭)합니다 — tmux 안에서 띄워도 작동합니다.
메시지는 push, 응답은 polling으로 받고, 모든 round trip은 ~/.teammate-mcp/logs/<날짜>.jsonl에 기록됩니다.
실측 round-trip 시간: 2 + 2 = 4 질문 기준 send → complete 3.0초 (대부분 Codex thinking 시간).
설치는 위 영문 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.
