wezmux-agent-mcp
Provides tools for discovering and controlling already-open WezTerm/Wezmux panes, sending and reading terminal text, focusing panes, gated pane spawning/closure, multi-agent messaging and coordination, advisory file locks, and updating Wezmux sidebar status via OSC 7777/OSC 9.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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:sqliteWAL)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=trueinjects a crisp wakeup prompt into an idle target pane so the peer agent reads its inbox immediately.Messages addressed to a raw
pane_idautomatically migrate if that pane later registers a custom agent name.
Existing-Pane-First & Spawn Permission Gating (
spawn_pane)MCP server instructions and Claude Code
SessionStartcontext instruct agents to operate already-open windows and panes instead of spawning new ones.Three-layer guard on
spawn_pane:Claude Code
permissions.ask+PreToolUsespawn-guardhook (permissionDecision: "ask").Schema & policy validation (
user_approved,reason,WEZMUX_SPAWN_POLICY=deny|ask|native_dialog).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
SessionStartand notifies Claude of unread inbox messages onUserPromptSubmit.
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 testRegister 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"]}'Enable Hooks & Spawn Permission Gate (Optional, Recommended)
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 all already-open windows, workspaces, tabs, and panes across live GUI instances |
| Send text or commands to an open | |
| Read terminal output from an open | |
| Focus an open | |
Gated Lifecycle |
| Restricted: create a split/tab/window (requires explicit user permission) |
| Close a specific | |
Multi-Agent Bus |
| Register a pane with a memorable name & role ( |
| List registered agents, live pane status, unread counts, and unregistered agent panes | |
| Send structured messages by agent name, | |
| Read unread or historical inbox messages | |
| Block until a new message arrives on an inbox or thread | |
Status & Safety |
| Update Wezmux sidebar state via OSC 7777 / OSC 9 and SQLite registry |
| Acquire, release, or list TTL-backed advisory file locks |
Environment Variables
WEZMUX_AGENT_DATA_DIR: Directory forbroker.db(defaults to~/.wezmux-agent-mcp)WEZMUX_CLI_BIN: Override path towezterm/wezterm.exeWEZMUX_SPAWN_POLICY:ask(default),deny(hard block allspawn_pane), ornative_dialogWEZMUX_SPAWN_OS_CONFIRM: Set to1to force a Windows confirmation dialog even if client permissions are bypassed
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Coding agents in one repo see each other, get warned before shared edits, and message.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to communicate and coordinate across tmux panes, allowing them to read, type, and send messages to each other without manual copy-pasting.9108MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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 npm1-
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT