wezterm-agent-mcp

Wezterm MCP Server — a programmable terminal control plane for multi-agent AI workflows.

Turns Wezterm into a remote-controllable terminal multiplexer that any AI coding CLI can be orchestrated through. One orchestrator agent spawns, monitors, and communicates with any number of AI agents running in parallel across multiple projects.

What This Does

• Spawn AI agents in Wezterm panes — Claude Code, Gemini CLI, Codex CLI, OpenCode, Goose

• Inject prompts into running agent sessions as if a human typed them

• Read output from any pane — passive (fast) or deep (asks agents for status)

• Manage windows — one window per project, auto-titled, with N/M numbering for duplicates

• Session recovery — save/restore full layouts including CLI session IDs after a crash

• Auto-skip permissions — each CLI's autonomous mode is handled automatically

• Cross-platform — Linux, macOS, and Windows via a platform abstraction layer

Related MCP server: Claude Team MCP Server

Architecture

+---------------------------------------------------+
|         Your AI Agent (Claude, etc.)              |
|                                                   |
|  "Launch 5 agents for the auth-service project"   |
|                       |                           |
|                  MCP Tool Calls                   |
|                       |                           |
+---------------------------------------------------+
|              wezterm-agent-mcp                    |
|             (this MCP server)                     |
|                       |                           |
|             wezterm cli commands                  |
|                       |                           |
+---------------------------------------------------+
|                    Wezterm                        |
|                                                   |
|  +-----------+ +-----------+ +-----------+        |
|  | Window 1  | | Window 2  | | Window 3  |        |
|  | auth-svc  | | pay-api   | | dashboard |        |
|  | +--+--+   | | +--+--+   | | +--+      |        |
|  | |C1|C2|   | | |C1|G1|   | | |C1|      |        |
|  | +--+--+   | | +--+--+   | | +--+      |        |
|  | |C3|C4|   | |           | |           |        |
|  | +--+--+   | |           | |           |        |
|  +-----------+ +-----------+ +-----------+        |
+---------------------------------------------------+

Quick Start

Prerequisites

• Node.js (v22.5+)

• Wezterm

Install

One command:

npm install -g wezterm-agent-mcp

Install automatically registers the MCP server globally for all AI coding tools:

One install, every project, every tool. Existing config files are merged — other MCP servers won't be touched.

To re-run manually or for per-project setup:

wezterm-agent-mcp init              # re-run global setup
wezterm-agent-mcp init --project    # per-project setup (current dir)
wezterm-agent-mcp init --root /path  # per-project setup (specific dir)

Wezterm Lua config (optional)

The package includes a wezterm.lua with auto-maximize, project-derived window titles, N/M numbering, auto tab titles, and F11 fullscreen. To use it:

# After npx downloads the package, copy from the npm cache:
npx -y wezterm-agent-mcp --help  # ensures package is cached
cp $(npm root -g)/wezterm-agent-mcp/wezterm.lua ~/.config/wezterm/wezterm.lua

# Or from a cloned repo:
cp wezterm.lua ~/.config/wezterm/wezterm.lua

Install from source

git clone https://github.com/multiagentcognition/wezterm-agent-mcp.git
cd wezterm-agent-mcp
npm install && npm run build
npx . init  # configure MCP for this project

Environment Variables

Supported CLIs

Each CLI's autonomous mode is handled automatically — flags, config files, and env vars are set before launch. Directory trust is pre-configured for Claude Code, Gemini, and Codex so no interactive prompts block startup.

MCP Tools (41 total)

Status & Lifecycle

Launching

Text I/O

Reading & Monitoring

Special Keys

Navigation & Layout

Titles & Workspace

Pane Management

Session Recovery

Session Recovery — How It Works

Session ID Capture

Each CLI stores sessions differently. The MCP reads session IDs from the filesystem:

Recovery Flow

1. Save — captures windows → tabs → panes with CLI type, session ID, and CWD

2. Crash — Wezterm dies but manifest and CLI session files persist

3. Recover — recreates windows/tabs/panes, validates each session ID exists on disk, resumes with --resume <id> or falls back to --continue

Platform Support

All OS-specific behavior is centralised in src/platform.ts with three implementations sharing a Unix base:

Testing

The test/ directory contains 11 test suites covering all 41 tools:

Tests are designed to be run by an AI agent via MCP tool calls — each test doc describes the steps, expected outputs, and pass criteria.

Known Limitations

• Wezterm version: Tested with 20240203. The format-window-title callback parameter types vary between versions.

• Session resume: Only works if the CLI's session file persists on disk. Short-lived sessions that get cleaned up before save can't be resumed.

• Deep read timeout: wez_read_all_deep waits up to 30 seconds per idle agent.

• screenshot_all_tabs: Flaky due to tab-switching timing — may capture 0 tabs.

• Stale mux servers: Wezterm can leave stale mux servers. After wez_kill_all, use wez_start before spawning new panes.

Disclaimer

USE AT YOUR OWN RISK. This software launches AI coding agents in autonomous mode with permissions to read, write, and execute files on your system. By design, it bypasses each CLI's safety prompts (--dangerously-skip-permissions, --sandbox=none, -a never, etc.) so agents can operate without human approval of individual actions.

This means:

• Agents can and will modify files, run shell commands, and make network requests without asking

• Multiple agents running in parallel can produce unexpected interactions

• There is no undo — changes agents make to your filesystem are immediate and permanent

• Session recovery resumes agents with full conversation context, which may include stale or incorrect instructions

Do not run this on production systems, with access to sensitive data, or in environments where unreviewed code execution is unacceptable. Use isolated directories, sandboxed environments, or disposable VMs when possible. The authors accept no liability for any damage, data loss, or unintended consequences resulting from use of this software.

License

PolyForm Strict 1.0.0 — personal and non-commercial use only. No modifications, no commercial/enterprise use. See LICENSE for full terms.