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

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.