Skip to main content
Glama
claude-mux-iterm

claude-mux-iterm

by GrigoriLab

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-iterm

Or with uv:

uv pip install claude-mux-iterm

Related 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 messages

Requirements

  • 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 tests

License

MIT License - see LICENSE file.

Available Tools

6 tools
acknowledge_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

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    Six tools is well-scoped for a session management and messaging system. Each tool contributes to the core workflow without redundancy or bloat.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers