claude-mux-iterm
Provides communication capabilities between iTerm2 panes for sending and receiving messages across sessions.
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., "@claude-mux-iterm broadcast PR #123 merged to main, please pull latest"
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.
claude-mux-iterm
MCP server enabling communication between Claude Code sessions in iTerm2 panes.
Primary use case: Notify other sessions when PR is merged to main so they can pull latest changes.
Installation
pip install claude-mux-itermOr with uv:
uv pip install claude-mux-itermRelated MCP server: claude-context-sync
Configuration
Add to your Claude Code MCP settings (~/.claude/settings.json or project-level):
{
"mcpServers": {
"claude-mux-iterm": {
"command": "uvx",
"args": ["claude-mux-iterm"]
}
}
}Or if installed with pip:
{
"mcpServers": {
"claude-mux-iterm": {
"command": "claude-mux-iterm"
}
}
}Tools
register_session(task_id)
Register the current iTerm2 session with a task ID. This allows other sessions to find and communicate with this session.
register_session("task-a")list_sessions()
List all registered active sessions.
list_sessions()send_message(target_task_id, content, source_task_id)
Send a message to a specific session.
send_message("task-b", "PR merged to main, please pull latest", "task-a")broadcast_message(content, source_task_id)
Send a message to all other active sessions.
broadcast_message("PR #123 merged to main, please pull latest", "task-a")list_messages(current_task_id, unread_only)
List messages received by this session.
list_messages("task-a", unread_only=True)acknowledge_message(message_id, current_task_id)
Mark a message as read/acknowledged.
acknowledge_message("msg_abc123", "task-a")Usage Example
Pane 1 (working on feature branch):
# Register this session
register_session("feature-auth")
# Check for messages periodically
list_messages("feature-auth", unread_only=True)Pane 2 (just merged a PR):
# Register this session
register_session("main-work")
# Notify all other sessions about the merge
broadcast_message("PR #42 merged to main with auth changes - please pull latest", "main-work")Message Format
Messages are injected into sessions using a wire format:
[CLAUDE-MUX-ITERM-MESSAGE]{"message_id":"msg_abc123",...}[/CLAUDE-MUX-ITERM-MESSAGE]Claude Code sessions can parse this format to extract the message content.
Storage
Session registrations and messages are stored in:
~/.claude-mux-iterm/
āāā sessions/
ā āāā {task_id}.json # Session registrations
āāā messages/
āāā {task_id}/
āāā inbox/ # Received messages
āāā outbox/ # Sent messages
āāā delivered/ # Acknowledged messagesRequirements
macOS (uses iTerm2 AppleScript)
iTerm2 running
Python 3.10+
Development
# Clone the repo
git clone https://github.com/GrigoriLab/claude-mux-iterm
cd claude-mux-iterm
# Install with dev dependencies
uv pip install -e ".[dev]"
# Run tests
uv run pytest
# Run type checking
uv run mypy src
# Run linting
uv run ruff check src testsLicense
MIT License - see LICENSE file.
Available Tools
6 toolsacknowledge_messageA
Mark a message as read/acknowledged.
Use this after you've processed a message to remove it from your unread messages.
Args: message_id: The ID of the message to acknowledge. current_task_id: Your current task ID.
Returns: Result indicating whether acknowledgement succeeded.
Example: >>> acknowledge_message("msg_abc123", "task-a") AcknowledgeMessageResult(success=True, ...)
Inputs: message_id (required), current_task_id (required). Returns: Result of acknowledging a message.
broadcast_messageA
Broadcast a message to all other active Claude Code sessions.
Use this to notify all other sessions about important events, like when a PR is merged to main.
Args: content: The message content to broadcast. source_task_id: Your current task ID (the sender). priority: Message priority: "normal", "high", or "urgent".
Returns: Result indicating how many sessions received the message.
Example: >>> broadcast_message("PR #123 merged to main, please pull latest", "task-a") SendMessageResult(success=True, delivered_to=["task-b", "task-c"], ...)
Inputs: content (required), source_task_id (required), priority. Returns: Result of sending a message.
list_messagesA
List messages received by this session.
Use this to see what other sessions have communicated to you.
Args: current_task_id: Your current task ID. unread_only: Only show messages not yet acknowledged.
Returns: List of messages with metadata.
Example: >>> list_messages("task-a", unread_only=True) ListMessagesResult(messages=[...], unread_count=3, ...)
Inputs: current_task_id (required), unread_only. Returns: Result of listing messages in inbox.
list_sessionsA
List all registered active iTerm2 sessions.
Use this to discover which other Claude Code sessions you can communicate with.
Returns: List of active sessions with their task IDs.
Example: >>> list_sessions() ListSessionsResult( sessions=[ Session(task_id="task-a", ...), Session(task_id="task-b", ...), ], total_count=2, ... )
Inputs: no named parameters. Returns: Result of listing sessions.
register_sessionA
Register the current iTerm2 session with a task ID.
This allows other Claude Code sessions to find and communicate with this session using the task ID.
Args: task_id: Unique identifier for this session (e.g., "task-a", "feature-auth"). Must be alphanumeric with hyphens/underscores, max 64 chars.
Returns: Result indicating whether registration succeeded.
Example: >>> register_session("task-a") RegisterSessionResult(success=True, task_id="task-a", ...)
Inputs: task_id (required). Returns: Result of registering a session.
send_messageA
Send a message to a specific Claude Code session.
Use this to communicate with another Claude instance working on a related task. The message will be injected into the target session.
Args: target_task_id: Task ID of the target session (e.g., "task-b"). content: The message content to send. source_task_id: Your current task ID (the sender). priority: Message priority: "normal", "high", or "urgent".
Returns: Result indicating whether the message was sent.
Example: >>> send_message("task-b", "PR merged to main, please pull latest", "task-a") SendMessageResult(success=True, message_id="msg_abc123", ...)
Inputs: content (required), source_task_id (required), target_task_id (required), priority. Returns: Result of sending a message.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: registration, listing sessions, unicast, broadcast, listing messages, and acknowledging. No two tools could be confused, even though send_message and broadcast_message share the sending concept, their targets differ.
All tool names follow the verb_noun pattern with snake_case, using consistent verbs like register, list, send, broadcast, and acknowledge. The naming is predictable and readable.
Six tools is well-scoped for a session management and messaging system. Each tool contributes to the core workflow without redundancy or bloat.
The core lifecycle is covered: register, discover, send, broadcast, read, and acknowledge. A notable gap is the lack of an unregister_session or cleanup mechanism, which could leave stale sessions, but agents can work around this in practice.
Maintenance
Related MCP Connectors
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Shared memory for a team in Claude Code: what one person records, everyone has.
Share context and questions between Claude instances ā VS Code, claude.ai web, and mobile.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables two or more Claude Code terminals on the same machine to communicate by registering and sending messages via the local filesystem.51MIT
- AlicenseNot gradedqualityDmaintenanceShare context, detect file conflicts, and send messages across parallel Claude Code sessions97 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables multiple Claude Code sessions to communicate and coordinate through broadcast and peer-to-peer messaging.1-
- AlicenseAqualityCmaintenanceEnables local messaging between Claude Code, Codex, Pi, and other coding-agent sessions on the same machine, allowing them to discover each other, send updates, ask questions, and reply.819 npm3AGPL 3.0