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.
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.
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-mux-iterm
Normally no /register command is necessary:
An iTerm session is identified at MCP startup and reuses its existing label.
Current Codex attaches _meta.threadId to 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).
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
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.
.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.
.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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It only states it returns an answer, but does not disclose potential side effects, timeout behavior, or whether it is a read-only operation. The agent lacks critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only two short sentences, no redundant information, and the primary action is front-loaded. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters and an output schema, but the description lacks detail on the output format and usage constraints. An agent can infer basic usage but may miss nuances like timeout meaning or question style expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description adds no information about the 'question' or 'timeout' parameters beyond what the schema provides. For a tool with 2 parameters and no enum constraints, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Ask' and the resource 'Claude pane', specifying that it returns an answer. The sibling tool 'ask_codex' helps differentiate, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool for 'plan, design feedback, or a sanity check' from Codex, providing clear context. However, it does not mention when to avoid using this tool in favor of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks behavioral details such as side effects, authentication requirements, rate limits, or any constraints. Merely states it returns an answer without elaboration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. First sentence is clear; second adds usage guidance. Could be slightly more efficient, but overall well-structured for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details on return value format despite having an output schema. No information on how Codex processes the question or what happens with the timeout. Minimal guidance for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in schema. The description does not explain the 'question' or 'timeout' parameters at all, adding zero value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'ask' and the resource 'Codex pane', with explicit mention of returning an answer. Distinguishes from sibling 'ask_claude' by naming Codex specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this from Claude when you want Codex's opinion, a code review, or to delegate execution to it', providing clear context and implicitly contrasting with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push a message to both panes without waiting for a reply.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses the key behavior of not waiting for a reply, but omits other behavioral traits like side effects, required permissions, or whether the message is stored. This is adequate for a simple tool but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It is appropriately sized and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description is minimally complete. It covers the core action and behavioral note, but does not explain 'both panes' or provide any usage context. It meets the minimum viability for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It says 'message' but adds no detail beyond the schema's type string. It does not explain format, constraints, or expected values, which is insufficient for a parameter with no description in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool pushes a message to both panes without waiting for a reply, using a specific verb and resource. This distinguishes it from sibling tools like ask_claude and ask_codex, which likely expect replies, and queue_status for status checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives. It does not mention when not to use it or compare it to sibling tools, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return queue counts + recent completions (debugging).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description clearly indicates it is a non-destructive read (returning counts and completions). There is no behavior beyond what is described, and no contradictions. A slight deduction for not explicitly stating read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence that immediately states the tool's purpose and context. No fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description sufficiently describes the tool's output. It could be considered complete for a simple status check, though mentioning any authentication or availability requirements would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 params, 100% coverage). The description adds value by specifying the return content (queue counts + recent completions). Baseline 4 is appropriate since the schema carries no burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns queue counts and recent completions, with 'debugging' context. It identifies the specific resource (queue status) and verb (return). It is well distinguished from siblings like ask_claude, ask_codex, and broadcast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for debugging via the parenthetical '(debugging)'. It does not explicitly state when to use vs. alternatives or when not to use, but the siblings are sufficiently different, so the guidance is adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0ask_claudeask_codexbroadcastqueue_statusScored 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).
Share context and questions between Claude instances — VS Code, claude.ai web, and mobile.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
