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 — это крошечный MCP-сервер, который предоставляет два инструмента для любого CLI, который его загружает:

• mcp__teammate__ask_codex(question, timeout) — вызов из Claude

• mcp__teammate__ask_claude(question, timeout) — вызов из Codex

Сервер использует Python API iTerm2 для отправки вопроса в другую панель и считывания ответа. Целевая панель определяется автоматически запущенным процессом — вам не нужно помечать вкладки или что-либо настраивать для каждого проекта.

Зачем?

Существующие системы для работы с несколькими агентами делятся на два лагеря:

1. Тяжеловесные: демон, файлы конфигурации для каждого проекта, непрозрачное состояние сессии. Отлично работает, пока что-то не сломается в 2 часа ночи, и вы не поймете почему.

2. Однопроцессные: одна модель, управляющая под-агентами внутри себя, поэтому пользователь видит только финальный ответ.

teammate-mcp предлагает третий вариант: два агента наглядно работают в вашем терминале рядом друг с другом, вы можете читать оба транскрипта в реальном времени, а вся «инфраструктура» — это несколько сотен строк 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}

Интервал ask.send → ask.complete составил 3,0 секунды для запроса «Сколько будет два плюс два? Ответь только цифрой» — большая часть этого времени уходит на размышления Codex, а не на мост. Пять последовательных запусков завершили цикл за 1,5–4,5 секунды.

Шесть независимых отчетов о времени выполнения, сохраненных в tests/results/, включены в репозиторий, чтобы вы могли самостоятельно проверить цифры.

Быстрый старт

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. Открытие панелей

У вас есть два варианта:

Вариант А — позвольте bin/team открыть для вас новое окно iTerm:

./bin/team

Вариант Б — используйте любое уже открытое окно 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 — везде, где наследуется переменная окружения.

   • в качестве запасного варианта используется сопоставление jobName / commandLine с предпочтением текущей рабочей директории (cwd).

3. async_send_text отправляет промпт + запрос завершить ответ маркером.

4. Опрашивается async_get_screen_contents на наличие маркера. Поскольку промпт, который мы ввели, содержит текст маркера (он эхом отображается в панели), сервер требует, чтобы маркер появился дважды, прежде чем считать ответ завершенным.

5. Ответ извлекается между двумя вхождениями маркера, записывается ask.complete, ответ возвращается вызывающей стороне.

Что на самом деле означает «без конфигурации»

Есть ровно одна вещь, которую нужно настроить (один раз): регистрация MCP в шаге 2 выше. После этого любое окно iTerm с панелями claude+codex просто работает — включая окна, которые были открыты до установки 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 с использованием заглушек (mocks). Сквозная демонстрация открывает реальное окно 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» — вы используете версию teammate-mcp старше 0.1.0. Обновитесь до main; инструменты теперь объявлены как async.

«Инструмент вернул ответ, который является просто эхом моего собственного промпта» — целевая панель промпта запускает не тот 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.)

«Маркер не обнаружен в течение времени ожидания» — агент на другом конце забыл вывести <<DONE_…>>. Добавьте явное напоминание в ваш AGENTS.md. Входящий в комплект шаблон уже включает это.

Лицензия

MIT — см. LICENSE.

Благодарности

Этот проект выкристаллизовался из обсуждений на основе публичных исследований того, как Claude Code и Codex используются в 2026 году:

• Статьи Anthropic Plan-Generate-Verify и Initializer + Coding Agent (Rajasekaran 2026-03; Justin Young 2025-11).

• claude-code-hooks-mastery от IndyDevDan за паттерны наблюдаемости.

• planning-with-files от OthmanAdi за идею «структурированные файлы связывают сессии, а не историю чата».

• Правило «цикла верификации» Бориса Черного из его треда How I use Claude Code.

• Цикл Ralph Wiggum от Джеффри Хантли за интуицию «свежий контекст для каждого хода».

Реализация обязана своими паттернами Python API iTerm документации iTerm2 по адресу https://iterm2.com/python-api/.

한국어 요약

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