Skip to main content
Glama

wezmux-agent-mcp

A multi-window, multi-agent MCP server and cross-platform hook bridge for WezTerm and vcabeli/wezmux.

It allows AI coding agents running inside different WezTerm / Wezmux windows, tabs, workspaces, and split panes (such as multiple Claude Code instances) to discover each other, exchange structured messages, coordinate file edits with advisory locks, and drive Wezmux's OSC 7777 sidebar status — while prioritizing already-open panes and requiring explicit user permission before creating new windows or splits.

Features

  • Cross-Instance & Multi-Window Discovery (list_panes, list_agents)

    • Discovers all live WezTerm / Wezmux GUI sockets (including Windows AF_UNIX sockets and stale PID filtering).

    • Detects active CLI agents (claude-code, codex, opencode, gemini, aider) and correlates them with registered agent identities.

  • Structured Multi-Agent Message Bus (node:sqlite WAL)

    • Point-to-point messaging by agent name or raw pane_id, plus * broadcast, message threading (thread_id, reply_to), and blocking wait (wait_for_message).

    • Optional wake_pane=true injects a crisp wakeup prompt into an idle target pane so the peer agent reads its inbox immediately.

    • Messages addressed to a raw pane_id automatically migrate if that pane later registers a custom agent name.

  • Existing-Pane-First & Spawn Permission Gating (spawn_pane)

    • MCP server instructions and Claude Code SessionStart context instruct agents to operate already-open windows and panes instead of spawning new ones.

    • Three-layer guard on spawn_pane:

      1. Claude Code permissions.ask + PreToolUse spawn-guard hook (permissionDecision: "ask").

      2. Schema & policy validation (user_approved, reason, WEZMUX_SPAWN_POLICY=deny|ask|native_dialog).

      3. Optional native Windows confirmation dialog (WEZMUX_SPAWN_OS_CONFIRM=1).

  • Windows & Unix OSC 7777 / OSC 9 Hook Bridge (wezmux-hook.mjs)

    • Brings Wezmux sidebar live status (working / idle / needs_input), tool indicators, subagent counters, and unread notifications to Windows (\\.\CONOUT$) as well as Unix (/dev/tty).

    • Auto-registers panes on SessionStart and notifies Claude of unread inbox messages on UserPromptSubmit.

  • Advisory File Locks (file_lock)

    • Prevents parallel agents in different panes from overwriting the same file concurrently.

Related MCP server: wezterm-agent-mcp

Requirements

  • Node.js >= 22.5 (uses built-in node:sqlite, no native C++ build tools required)

  • WezTerm or Wezmux (vcabeli/wezmux)

Installation

git clone https://github.com/AnAcretiondisk9986/wezmux-agent-mcp.git
cd wezmux-agent-mcp
npm install
npm test

Register with Claude Code

claude mcp add-json --scope user wezmux-agent '{"type":"stdio","command":"node","args":["--no-warnings","/absolute/path/to/wezmux-agent-mcp/server.mjs"]}'

Merge examples/claude-settings.hooks.json into ~/.claude/settings.json (replacing /path/to/wezmux-agent-mcp with your cloned path).

For vcabeli/wezmux, see examples/wezmux.lua for a starter ~/.wezmux.lua configuration.

Exposed MCP Tools (13)

Category

Tool

Description

Existing Panes

list_panes

List all already-open windows, workspaces, tabs, and panes across live GUI instances

send_text

Send text or commands to an open pane_id (optional submit, instance_pid)

get_text

Read terminal output from an open pane_id (ANSI stripped by default)

focus_pane

Focus an open pane_id

Gated Lifecycle

spawn_pane

Restricted: create a split/tab/window (requires explicit user permission)

kill_pane

Close a specific pane_id

Multi-Agent Bus

register_agent

Register a pane with a memorable name & role (architect, coder, etc.)

list_agents

List registered agents, live pane status, unread counts, and unregistered agent panes

send_message

Send structured messages by agent name, pane_id, or *; optional wake_pane

read_messages

Read unread or historical inbox messages

wait_for_message

Block until a new message arrives on an inbox or thread

Status & Safety

set_wezmux_status

Update Wezmux sidebar state via OSC 7777 / OSC 9 and SQLite registry

file_lock

Acquire, release, or list TTL-backed advisory file locks

Environment Variables

  • WEZMUX_AGENT_DATA_DIR: Directory for broker.db (defaults to ~/.wezmux-agent-mcp)

  • WEZMUX_CLI_BIN: Override path to wezterm / wezterm.exe

  • WEZMUX_SPAWN_POLICY: ask (default), deny (hard block all spawn_pane), or native_dialog

  • WEZMUX_SPAWN_OS_CONFIRM: Set to 1 to force a Windows confirmation dialog even if client permissions are bypassed

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to communicate and coordinate across tmux panes, allowing them to read, type, and send messages to each other without manual copy-pasting.
      9
      108
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables orchestration of multiple AI coding agents (Claude Code, Gemini CLI, etc.) in isolated Wezterm panes, allowing one agent to spawn, monitor, and communicate with others across projects.
      8 npm
      1
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-compatible AI agents to read, type, and send messages into other tmux panes, allowing them to coordinate multi-agent workflows, monitor processes, and exchange context without manual copy-pasting.
      49 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents running in separate tmux panes to read each other's output, send messages and keystrokes, and coordinate multi-agent workflows through standard MCP tool calls. It lets existing MCP-compatible agents communicate cross-pane without requiring a multi-agent framework or extra infrastructure beyond tmux.
      49 npm
      MIT