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는 이를 로드하는 CLI에 두 가지 도구를 제공하는 작은 MCP 서버입니다:

• mcp__teammate__ask_codex(question, timeout) — Claude에서 호출

• mcp__teammate__ask_claude(question, timeout) — Codex에서 호출

이 서버는 iTerm2 Python API를 사용하여 질문을 다른 페인으로 보내고 응답을 읽어옵니다. 대상 페인은 실행 중인 프로세스에 의해 자동으로 감지되므로, 탭에 라벨을 붙이거나 프로젝트별로 미리 설정할 필요가 없습니다.

왜 필요한가요?

기존의 멀티 에이전트 도구들은 크게 두 가지 유형으로 나뉩니다:

1. 헤비급: 데몬, 프로젝트별 설정 파일, 불투명한 세션 상태. 새벽 2시에 문제가 발생하면 원인을 알 수 없어 매우 불편합니다.

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개의 독립적인 타이밍 보고서가 저장소에 포함되어 있어 직접 수치를 검증할 수 있습니다.

빠른 시작

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, 로그인 셸, pyenv 래퍼를 통해서도 작동합니다 — 환경 변수가 상속되는 곳이라면 어디서든 가능합니다.

   • 마지막으로 현재 작업 디렉토리(cwd)를 우선순위로 하여 jobName / commandLine 매칭을 수행합니다.

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" — 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에게 물어봐"라고 시키면 됩니다.