teammate-mcp

Claude CodeとOpenAI Codexが、iTermのペインを通じて互いに質問できるようにします。デーモンは不要。プロジェクトごとに手動で編集する.configもありません。2つのペインを開くだけで、彼らは会話を始められます。

┌──────────── 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に対して2つのツールを提供する小さなMCPサーバーです：

• mcp__teammate__ask_codex(question, timeout) — Claudeから呼び出し

• mcp__teammate__ask_claude(question, timeout) — Codexから呼び出し

このサーバーはiTerm2 Python APIを使用して、質問をもう一方のペインに送信し、返信を読み取ります。ターゲットのペインは実行中のプロセスによって自動的に検出されるため、タブにラベルを付けたり、プロジェクトごとに事前設定したりする必要はありません。

なぜこれが必要か？

既存のマルチエージェント用ハーネスは、大きく分けて2つのキャンプに分かれています：

1. 重量級: デーモン、プロジェクトごとの設定ファイル、不透明なセッション状態。午前2時に何かが壊れて原因がわからなくなるまでは素晴らしいものです。

2. 単一プロセス: 1つのモデルが内部でサブエージェントを調整するため、ユーザーには最終的な回答しか見えません。

teammate-mcpは第3の選択肢を目指しています。2つのエージェントがターミナル上で隣り合って目に見える形で動作し、両方のやり取りをリアルタイムで読むことができ、唯一の「インフラ」はテキストを送信して画面を読み取る数百行の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}

「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. ペインを開く

2つの選択肢があります：

オプションA — bin/teamに新しいiTermウィンドウを開かせる：

./bin/team

オプションB — すでに開いているiTermウィンドウを使用する。1つのペインでclaudeを、もう1つのペインで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をポーリングします。入力したプロンプト自体にマーカーテキストが含まれている（ペインにエコーされる）ため、サーバーは返信が完了したと判断する前に、マーカーが2回出現することを要求します。

5. 2つのマーカーの間の回答を切り出し、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」 — 設定 → 一般 → マジック → 「Python APIを有効にする」にチェックを入れてください。teammate-mcpが最初に接続する際、iTermは許可を求めますので、「許可」をクリックしてください。

「asyncio.run() cannot be called from a running event loop」 — 0.1.0より古いteammate-mcpを使用しています。mainをプルしてください。ツールは現在asyncとして宣言されています。

「ツールが自分のプロンプトエコーのみを返した」 — プロンプトのターゲットペインで間違ったCLIが実行されています（例：ルックアップが同じプロセスを実行している隣接ペインを選択した）。ペインを明示的に固定してください：

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

（各ペインのunique idは、ウィンドウメニュー → ウィンドウ設定 → 識別子、またはAppleScriptから読み取ることができます。）

「タイムアウト内にマーカーが検出されなかった」 — 相手側のエージェントが<<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の2つのペインにclaudeとcodexを起動するだけです。ラベルも、configも、デーモンもありません。

• iTerm Python APIで相手のペインを自動検知（実行プロセス + 環境変数TERM_SESSION_IDマッチング）します — tmux内で起動しても動作します。

• メッセージはpush、応答はpollingで受け取り、すべてのラウンドトリップは~/.teammate-mcp/logs/<日付>.jsonlに記録されます。

• 実測ラウンドトリップ時間: 2 + 2 = 4の質問基準でsend → complete 3.0秒 (大部分はCodexの思考時間)。

インストールは上記の英語のクイックスタート1〜3段階、使い方は普段通りClaudeに「Codexに聞いてみて」と指示するだけです。