teammate-mcp

Lassen Sie Claude Code und OpenAI Codex sich gegenseitig Fragen über Ihre iTerm-Fenster stellen. Kein Daemon. Keine .config, die Sie pro Projekt manuell bearbeiten müssen. Öffnen Sie einfach zwei Fenster und sie können miteinander kommunizieren.

┌──────────── 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 ist ein kleiner MCP-Server, der zwei Tools für das CLI bereitstellt, das ihn lädt:

• mcp__teammate__ask_codex(question, timeout) — Aufruf von Claude

• mcp__teammate__ask_claude(question, timeout) — Aufruf von Codex

Der Server verwendet die iTerm2 Python API, um die Frage in das andere Fenster zu übertragen und die Antwort zurückzulesen. Das Zielfenster wird vom laufenden Prozess automatisch erkannt – Sie müssen keine Tabs beschriften oder irgendetwas pro Projekt vorkonfigurieren.

Warum?

Bestehende Multi-Agenten-Systeme lassen sich in zwei Kategorien einteilen:

1. Schwergewichtig: ein Daemon, Konfigurationsdateien pro Projekt, undurchsichtiger Sitzungsstatus. Großartig, bis um 2 Uhr morgens etwas kaputtgeht und man nicht sieht, warum.

2. Einzelprozess: Ein Modell, das Unteragenten intern orchestriert, sodass der Benutzer nur das Endergebnis sieht.

teammate-mcp zielt auf eine dritte Option ab: Die beiden Agenten laufen sichtbar in Ihrem Terminal nebeneinander, Sie können beide Transkripte in Echtzeit lesen, und die einzige "Infrastruktur" sind ein paar hundert Zeilen Python, die Text übertragen und Bildschirminhalte lesen.

Related MCP server: claude-mux-iterm

Verifizierter bidirektionaler Roundtrip

Live aufgezeichnet während der Entwicklung auf 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}

Das Intervall ask.send → ask.complete betrug 3,0 Sekunden für die Aufforderung "Was ist zwei plus zwei? Antworte nur mit der Ziffer" – der Großteil davon ist die Denkzeit von Codex, nicht die der Brücke. Fünf aufeinanderfolgende Durchläufe schlossen den Kreislauf jeweils in 1,5 – 4,5 Sekunden.

Sechs unabhängige Zeitmessungsberichte, die in tests/results/ erfasst wurden, sind im Repository enthalten, damit Sie die Zahlen selbst prüfen können.

Schnellstart

1. Installation

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

2. Registrieren Sie den Server bei beiden CLIs

# 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. Öffnen Sie die Fenster

Sie haben zwei Optionen:

Option A — lassen Sie bin/team ein neues iTerm-Fenster für Sie öffnen:

./bin/team

Option B — verwenden Sie ein beliebiges iTerm-Fenster, das bereits geöffnet ist. Führen Sie einfach claude in einem Fenster und codex in einem anderen aus. teammate-mcp findet sie anhand des Prozessnamens; keine Beschriftungen erforderlich.

4. (Einmalig) Geben Sie den Agenten die Betriebsregeln

Legen Sie templates/AGENTS.md in Ihr Projektstammverzeichnis. Sowohl Claude Code als auch Codex werden sie automatisch erkennen (es ist die Konvention, der beide folgen). Die Datei teilt ihnen mit, wie und wann sie sich gegenseitig aufrufen sollen.

5. Ausprobieren

Im Claude-Fenster:

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

Sie werden sehen, wie Claude mcp__teammate__ask_codex aufruft, die Frage im rechten Fenster erscheint, Codex antwortet und Claude die Antwort weiterleitet.

Funktionsweise

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

Für jeden ask_codex (oder ask_claude) Aufruf:

1. Generieren Sie einen eindeutigen Marker, stellen Sie die Nachricht in die festplattenbasierte Warteschlange (pending/ → inflight/ atomares Umbenennen).

2. Lokalisieren Sie das Zielfenster:

   • bevorzugen Sie die Umgebungsvariable TEAMMATE_<UPPER>_SESSION_ID

   • andernfalls listen Sie alle laufenden Prozesse auf (ps-Stil), finden Sie jeden claude- oder codex-Prozess, lesen Sie dessen TERM_SESSION_ID Umgebungsvariable und gleichen Sie diese mit der Sitzungsliste von iTerm ab. Dies funktioniert über tmux, Login-Shells und pyenv-Wrapper – überall dort, wo die Umgebungsvariable vererbt wird.

   • greifen Sie auf jobName / commandLine Abgleich mit bevorzugtem Arbeitsverzeichnis (cwd) zurück.

3. async_send_text überträgt den Prompt + eine Anforderung, die Antwort mit dem Marker zu beenden.

4. Pollen Sie async_get_screen_contents nach dem Marker. Da der von uns eingegebene Prompt den Markertext enthält (er wird im Fenster wiederholt), erfordert der Server, dass der Marker zweimal erscheint, bevor die Antwort als vollständig betrachtet wird.

5. Schneiden Sie die Antwort zwischen den beiden Marker-Vorkommen aus, protokollieren Sie ask.complete und geben Sie die Antwort an den Aufrufer zurück.

Was "keine Konfiguration" tatsächlich bedeutet

Es gibt genau eine Sache, die (einmalig) konfiguriert werden muss: die MCP-Registrierung in Schritt 2 oben. Danach funktioniert jedes iTerm-Fenster mit claude+codex-Fenstern einfach so – einschließlich Fenstern, die bereits vor der Installation von teammate-mcp geöffnet waren.

Sie schreiben niemals eine .teammate.toml, Sie führen niemals teammate start aus, Sie müssen sich nie merken, welche Sitzungs-ID welche ist.

Testen

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

Die Unit-Tests decken die Warteschlange, die ANSI/Marker-Verarbeitung, den Server-Modul-Import und die iTerm-Sitzungserkennungslogik mit Mocks ab. Die End-to-End-Demo öffnet ein echtes iTerm-Fenster und führt einen Claude → Codex → Claude Roundtrip durch; dies erfordert, dass beide CLIs eingeloggt sind, und verursacht deren normale API-Gebühren.

Zeitberichte pro Durchlauf werden in tests/results/*.jsonl geschrieben. Diejenigen, die bereits im Repository enthalten sind, sind echt, nicht synthetisch.

Fehlerbehebung

"iTerm Python API is not enabled" — Einstellungen → Allgemein → Magic → "Enable Python API" ✓. Wenn sich teammate-mcp zum ersten Mal verbindet, fragt iTerm ebenfalls nach der Erlaubnis; klicken Sie auf Allow.

"asyncio.run() cannot be called from a running event loop" — Sie verwenden eine teammate-mcp-Version älter als 0.1.0. Führen Sie git pull main aus; die Tools sind jetzt als async deklariert.

"Tool returned an answer that's just my own prompt echo" — das Ziel-Fenster für den Prompt führt das falsche CLI aus (z. B. hat die Suche ein Geschwisterfenster gefunden, das denselben Prozess ausführte). Pinnen Sie das Fenster explizit:

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

(Sie können die unique id jedes Fensters über Window menu → Window Settings → Identifier oder via AppleScript lesen.)

"Marker not detected within timeout" — der Agent auf der anderen Seite hat vergessen, <<DONE_…>> auszugeben. Fügen Sie eine explizite Erinnerung in Ihre AGENTS.md ein. Die mitgelieferte Vorlage enthält dies bereits.

Lizenz

MIT — siehe LICENSE.

Danksagungen

Dieses Projekt kristallisierte sich aus Gesprächen über öffentliche Forschung dazu heraus, wie Claude Code und Codex im Jahr 2026 betrieben werden:

• Anthropics Plan-Generate-Verify und Initializer + Coding Agent Harness-Papiere (Rajasekaran 2026-03; Justin Young 2025-11).

• IndyDevDans claude-code-hooks-mastery für die Observability-Muster.

• OthmanAdis planning-with-files für die Idee "strukturierte Dateien überbrücken Sitzungen, nicht den Chatverlauf".

• Boris Chernys "Verifizierungsschleifen"-Regel aus seinem How I use Claude Code-Thread.

• Geoffrey Huntleys Ralph Wiggum Schleife für die Intuition "frischer Kontext pro Durchgang".

Die Implementierung verdankt ihre iTerm Python API-Muster den iTerm2-Dokumenten unter https://iterm2.com/python-api/.

Zusammenfassung (Koreanisch)

Dies ist ein kleiner MCP-Server, der es claude / codex ermöglicht, sich gegenseitig Fragen zu stellen, ohne dass eine Vorabkonfiguration wie CCB erforderlich ist.

• Öffnen Sie einfach claude und codex in zwei iTerm-Fenstern. Es gibt keine Labels, keine Config und keinen Daemon.

• Die iTerm Python API erkennt das Gegenfenster automatisch (Abgleich von laufendem Prozess + Umgebungsvariable TERM_SESSION_ID) – es funktioniert auch innerhalb von tmux.

• Nachrichten werden per Push übertragen, Antworten per Polling empfangen, und jeder Roundtrip wird in ~/.teammate-mcp/logs/<Datum>.jsonl protokolliert.

• Gemessene Roundtrip-Zeit: 3,0 Sekunden für eine 2 + 2 = 4 Frage (send → complete) (hauptsächlich Codex-Denkzeit).

Die Installation erfolgt über die Schritte 1-3 des englischen Schnellstarts, die Verwendung ist einfach: Bitten Sie Claude wie gewohnt: "Frag Codex danach".