teammate-mcp

Deja que Claude Code y OpenAI Codex se hagan preguntas entre sí a través de tus paneles de iTerm. Sin demonios. Sin archivos .config que tengas que editar manualmente por proyecto. Solo abre dos paneles y podrán hablar.

┌──────────── 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 es un pequeño servidor MCP que expone dos herramientas a cualquier CLI que lo cargue:

• mcp__teammate__ask_codex(question, timeout) — llamar desde Claude

• mcp__teammate__ask_claude(question, timeout) — llamar desde Codex

El servidor utiliza la API de Python de iTerm2 para enviar la pregunta al otro panel y leer la respuesta. El panel de destino es detectado automáticamente por el proceso en ejecución: no etiquetas pestañas, no preconfiguras nada por proyecto.

¿Por qué?

Los arneses multi-agente existentes caen en dos campos:

1. Pesados: un demonio, archivos de configuración por proyecto, estado de sesión opaco. Genial hasta que algo se rompe a las 2 a.m. y no puedes ver por qué.

2. Proceso único: un modelo que orquesta subagentes internamente, por lo que el usuario solo ve la respuesta final.

teammate-mcp apunta a una tercera opción: los dos agentes se ejecutan visiblemente en tu terminal uno al lado del otro, puedes leer ambas transcripciones en tiempo real, y la única "infraestructura" son unos pocos cientos de líneas de Python que envían texto y leen pantallas.

Related MCP server: claude-mux-iterm

Viaje de ida y vuelta bidireccional verificado

Capturado en vivo durante el desarrollo en 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}

El intervalo ask.send → ask.complete fue de 3.0 segundos para un prompt de "¿Cuánto es dos más dos? Responde solo con el dígito" — la mayor parte es tiempo de pensamiento de Codex, no del puente. Cinco ejecuciones consecutivas cerraron el ciclo en 1.5 – 4.5 segundos.

Se incluyen seis informes de tiempo independientes capturados en tests/results/ en el repositorio para que puedas auditar los números tú mismo.

Inicio rápido

1. Instalar

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

2. Registrar el servidor con ambas 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. Abrir los paneles

Tienes dos opciones:

Opción A — deja que bin/team abra una ventana nueva de iTerm para ti:

./bin/team

Opción B — usa cualquier ventana de iTerm que ya tengas abierta. Solo ejecuta claude en un panel y codex en otro. teammate-mcp los encuentra por nombre de proceso; no se necesitan etiquetas.

4. (Una sola vez) Entrega a los agentes las reglas de operación

Coloca templates/AGENTS.md en la raíz de tu proyecto. Tanto Claude Code como Codex lo detectarán automáticamente (es la convención que ambos siguen). El archivo les indica cómo y cuándo llamarse entre sí.

5. Pruébalo

En el panel de Claude:

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

Verás a Claude llamar a mcp__teammate__ask_codex, la pregunta aparecer en el panel de la derecha, Codex responder, y Claude transmitir la respuesta.

Cómo funciona

┌──────────────────────────────────────────────────────┐
│  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         │
└──────────────────────────────────────────────────────┘

Para cada llamada ask_codex (o ask_claude):

1. Generar un marcador único, encolar el mensaje en la cola del disco (pending/ → inflight/ renombrado atómico).

2. Localizar el panel de destino:

   • preferir la anulación de entorno TEAMMATE_<UPPER>_SESSION_ID

   • de lo contrario, enumerar todos los procesos activos (estilo ps), encontrar cualquier proceso claude o codex, leer su variable de entorno TERM_SESSION_ID, y compararla con la lista de sesiones de iTerm. Esto funciona a través de tmux, shells de inicio de sesión y wrappers de pyenv — donde sea que la variable de entorno sea heredada.

   • recurrir a la coincidencia de jobName / commandLine con preferencia de cwd.

3. async_send_text el prompt + una solicitud para terminar la respuesta con el marcador.

4. Sondear async_get_screen_contents para el marcador. Debido a que el prompt que escribimos contiene el texto del marcador (se hace eco en el panel), el servidor requiere que el marcador aparezca dos veces antes de tratar la respuesta como completa.

5. Cortar la respuesta entre las dos apariciones del marcador, registrar ask.complete, devolver la respuesta al llamador.

Qué significa realmente "sin configuración"

Hay exactamente una cosa que configurar (una vez): el registro MCP en el paso 2 anterior. Después de eso, cualquier ventana de iTerm con paneles claude+codex simplemente funciona, incluidas las ventanas que ya estaban abiertas antes de que instalaras teammate-mcp.

Nunca escribes un .teammate.toml, nunca haces teammate start, nunca tienes que recordar qué id de sesión es cuál.

Pruebas

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

Las pruebas unitarias cubren la cola, el manejo de ANSI/marcador, la importación del módulo del servidor y la lógica de descubrimiento de sesiones de iTerm con mocks. La demostración de extremo a extremo abre una ventana real de iTerm y ejercita un viaje de ida y vuelta Claude → Codex → Claude; requiere que ambas CLI hayan iniciado sesión e incurrirá en sus cargos normales de API.

Los informes de tiempo por ejecución se escriben en tests/results/*.jsonl. Los que ya están confirmados en el repositorio son reales, no sintéticos.

Solución de problemas

"iTerm Python API is not enabled" — Ajustes → General → Magic → "Enable Python API" ✓. La primera vez que teammate-mcp se conecta, iTerm también solicita permiso; haz clic en Allow.

"asyncio.run() cannot be called from a running event loop" — estás en una versión de teammate-mcp anterior a la 0.1.0. Haz un pull de main; las herramientas ahora se declaran async.

"Tool returned an answer that's just my own prompt echo" — el panel de destino del prompt está ejecutando la CLI incorrecta (por ejemplo, la búsqueda eligió un panel hermano que tenía el mismo proceso ejecutándose). Fija el panel explícitamente:

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

(Puedes leer el unique id de cada panel desde Window menu → Window Settings → Identifier, o a través de AppleScript.)

"Marker not detected within timeout" — el agente en el otro extremo olvidó emitir <<DONE_…>>. Agrega un recordatorio explícito en tu AGENTS.md. La plantilla incluida ya lo incluye.

Licencia

MIT — ver LICENSE.

Agradecimientos

Este proyecto se cristalizó a partir de conversaciones sobre investigaciones públicas sobre cómo se están ejecutando Claude Code y Codex en 2026:

• Los documentos de arneses Plan-Generate-Verify e Initializer + Coding Agent de Anthropic (Rajasekaran 2026-03; Justin Young 2025-11).

• claude-code-hooks-mastery de IndyDevDan para los patrones de observabilidad.

• planning-with-files de OthmanAdi para la idea de "archivos estructurados que unen sesiones, no historial de chat".

• La regla del "bucle de verificación" de Boris Cherny de su hilo How I use Claude Code.

• El bucle Ralph Wiggum de Geoffrey Huntley para la intuición de "contexto fresco por turno".

La implementación debe sus patrones de API de Python de iTerm a los documentos de iTerm2 en https://iterm2.com/python-api/.

Resumen en coreano

Es un pequeño servidor MCP que permite que claude / codex se hagan preguntas entre sí sin configuraciones previas como CCB.

• Solo tienes que abrir claude y codex en dos paneles de iTerm. No hay etiquetas, ni configuración, ni demonios.

• Detecta automáticamente el panel opuesto con la API de Python de iTerm (proceso en ejecución + coincidencia de variable de entorno TERM_SESSION_ID) — funciona incluso si se abre dentro de tmux.

• Los mensajes se envían mediante push, las respuestas se reciben mediante polling, y todos los viajes de ida y vuelta se registran en ~/.teammate-mcp/logs/<fecha>.jsonl.

• Tiempo de ida y vuelta medido: 3.0 segundos para send → complete basado en la pregunta 2 + 2 = 4 (la mayor parte es el tiempo de pensamiento de Codex).

La instalación sigue los pasos 1~3 del inicio rápido en inglés, y para usarlo, simplemente pídele a Claude como siempre: "Pregúntale a Codex".