teammate-mcp
Enables local two-way conversations between Claude and Codex sessions with durable messaging and queue inspection.
ask_codex: Ask Codex a question from Claude and get its answer (e.g., opinion, code review, delegated execution).ask_claude: Ask Claude a question from Codex and get its answer (e.g., plan, design feedback, sanity check).broadcast: Push a message to both panes without waiting for a reply.queue_status: Return queue counts and recent completions for debugging.
Enables OpenAI Codex to send questions to Claude via iTerm panes and retrieve responses, facilitating multi-agent collaboration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@teammate-mcp Ask Codex to write a quick Python script to merge two CSV files."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
teammate-mcp
Local two-way conversations between Claude Code/iTerm sessions and Codex threads. Messages have stable IDs, durable history and correlated replies. A transport receipt is distinct from an answer.
Setup
From this repository:
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
claude mcp add --scope user teammate -- "$PWD/.venv/bin/teammate-mcp" serve
codex mcp add teammate -- "$PWD/.venv/bin/teammate-mcp" serveFor native Claude queue delivery, start Claude with ./bin/claude-channel and
accept its local-development channel confirmation. This is required by Claude;
MCP registration alone does not enable channel input. Keep an existing draft
untouched by starting a separate channel session for the initial check.
Add the server to each client you use; do not add duplicate entries if it is
already configured. Existing processes need one teammate MCP reconnect to load
updated code. bin/install-claude additionally installs slash commands and
inbox hooks while preserving unrelated settings.
Verified environment: macOS, iTerm2, Claude Code 2.1.259, Codex 0.153.4.
iTerm delivery needs its automation/Python API access. Pane-free automatic
Codex delivery needs the local app-server control socket and a thread with
canAcceptDirectInput=true. There is no cross-machine relay in this package.
Related MCP server: claude-coder-mac-mcp
Automatic registration
Normally no /register command is necessary:
An iTerm session is identified at MCP startup and reuses its existing label.
Current Codex attaches
_meta.threadIdto tool calls. The first call registers that exact thread and enables idle delivery. Identity is isolated per request, so a shared MCP process cannot mix concurrent callers through global env state.A standalone Codex CLI without a usable app-server transport keeps its verified physical pane address. No other pane is guessed from title or working directory.
A reconnect keeps existing policy, including an explicit automatic-delivery disable.
A pane-free connection cannot be assigned before the client provides its identity;
its first tool invocation completes setup. Call connection_status() to see
address, transport, readiness, identity source and any setup error. Older clients
that provide neither pane identity nor thread metadata need explicit recovery
registration (register_self / register_mailbox).
Conversation tools
Tool | Purpose |
| Automatic setup and this caller's readiness |
| Live panes plus registered Codex mailbox addresses |
| Send a question to a registered label |
| Answer the original sender with question/conversation IDs |
| Inspect this session's unprocessed messages |
| Record completion without another message |
| Inspect queued/waiting/delivered/retry/failed/uncertain state |
| Retry a known failure for the receiving session |
| Configure the owning Codex thread |
| Explicit recovery/custom registration |
| Explicit registration for the calling environment |
Use explicit target labels. sent/queued is not a response. A reply includes
in_reply_to and conversation_id; an already-sent reply is not sent again.
If reply receipt writing fails, repeating the reply finishes the receipt without
repeating the send. Do not turn acknowledgements into an infinite ping-pong loop.
Registration skill · Conversation skill
Delivery and recovery
Codex: idle policy waits for the current turn to finish, then uses app-server
turn/start. Explicit immediate policy uses turn/steer for the matching active
turn. Messages remain durable until processed. A disconnected worker is restarted
on the next applicable tool call or send. Known pre-dispatch failures retry with
backoff; an ambiguous dispatch is never blindly resent.
Claude: MCP notifications/claude/channel events enter the native execution
queue independently of the draft editor. A nonce handshake must be received and
acknowledged by Claude before the channel is marked ready. No draft text is read,
cleared, restored or submitted. An unsent draft is not in the execution queue;
peer events can arrive before its later submission. Claude controls scheduling
of already-running turns and previously submitted messages.
Keyboard transport is disabled by default, including the watchdog. A channel
that is unavailable leaves mail queued with an explicit waiting state; it does
not fall back to typing into the editor. The old keyboard path remains only for
explicit compatibility testing under TEAMMATE_LEGACY_PANE_INPUT=1; the channel
launcher unsets it. See native channel setup and acceptance.
State lives under ~/.teammate-mcp/: registry, per-address inbox/history/processed,
response records, delivery state and worker health. Inspect
run/mailbox-worker.log and logs/watchdog.log for diagnostic errors. A failed
or uncertain status is not silently called complete. retry_delivery refuses
accepted/ambiguous deliveries; inspect the recipient before any manual resend.
Fresh MCP connection for old running clients
.venv/bin/python scripts/mcp_call.py connection_status '{}'
.venv/bin/python scripts/mcp_call.py ask '{"target":"claude39","question":"Hello"}'This is an actual MCP ClientSession.call_tool connection, not direct file-based
message simulation. It preserves the caller's real environment. For complex
message text use a subprocess argument list and json.dumps rather than shell
string interpolation. A native current Codex tool call also supplies thread
metadata automatically; the helper is not required after reconnecting.
Verification
.venv/bin/python -m pytest tests --ignore=tests/test_e2e.py -qThe separate iTerm sanity test needs an interactive desktop. Live two-way, automatic active/idle delivery, word-chain and first-call registration evidence is in reliable conversations and automatic setup.
Available Tools
4 toolsask_claudeA
Ask the Claude pane a question and return its answer.
Use this from Codex when you want Claude's plan, design feedback, or a sanity check.
Inputs: question (required), timeout. Returns: result
ask_codexB
Ask the Codex pane a question and return its answer.
Use this from Claude when you want Codex's opinion, a code review, or to delegate execution to it.
Inputs: question (required), timeout. Returns: result
broadcastB
Push a message to both panes without waiting for a reply.
Inputs: message (required). Returns: result
queue_statusA
Return queue counts + recent completions (debugging).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: ask_claude and ask_codex target specific panes, broadcast sends to both without waiting, and queue_status provides debugging info. No overlap.
All tool names use lowercase with underscores and follow a consistent verb_noun pattern (ask_claude, ask_codex, queue_status) or are a clear verb (broadcast).
4 tools is well-scoped for the server's purpose of inter-pane communication, covering questioning each pane, broadcasting, and status monitoring.
Core workflows are covered, but a minor gap exists: there is no tool to send a one-way message to a specific pane without expecting a reply (only broadcast to both).
Maintenance
Related MCP Connectors
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables communication between Claude Code sessions in iTerm2 panes, primarily for notifying other sessions when a PR is merged to main so they can pull latest changes.642 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to spawn new Claude Code instances in iTerm2 windows for interactive coding sessions.10 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code and OpenAI Codex to exchange messages directly within their sessions, including optional cross-review of plans, without copying between terminals.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents running in separate tmux panes to see each other's output, send tasks and messages across panes, and coordinate multi-agent workflows through standard MCP tool calls. It talks to tmux directly, so Claude Code, Codex, Gemini CLI, Kimi CLI and other MCP-compatible agents can collaborate without copy-pasting or custom glue code.49 npmMIT