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

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:

| Config file | For | |---|---| | ~/.claude.json | Claude Code | | ~/.cursor/mcp.json | Cursor | | VS Code user mcp.json | VS Code (platform-specific path) | | ~/.gemini/settings.json | Gemini CLI | | ~/.config/opencode/... | OpenCode (platform-specific path) |

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

| Variable | Description | Default | |---|---|---| | WEZ_PROJECT_ROOT | Default working directory for all panes | process.cwd() | | MACP_PROJECT_ROOT | Fallback if WEZ_PROJECT_ROOT not set | — | | WEZ_GIT_BRANCH | Informational git branch (not enforced) | auto-detected |

Supported CLIs

| CLI | Binary | Skip-permissions | Session resume | |---|---|---|---| | Claude Code | claude | --dangerously-skip-permissions | --resume <session-id> or --continue | | Gemini CLI | gemini | --sandbox=none | --resume latest | | Codex CLI | codex | -a never | codex resume <session-id> or resume --last | | OpenCode | opencode | Config: permission: "allow" | --session <id> or --continue | | Goose | goose | Env: GOOSE_MODE=auto | goose session --resume --session-id <id> |

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

| Tool | Description | |---|---| | wez_status | Full status: windows, tabs, panes with CLI detection and state | | wez_list | List all panes with CLI type, state, CWD | | wez_start | Start Wezterm if not running |

Launching

| Tool | Description | |---|---| | wez_launch_agents | Open a project window with N agents (auto-grid layout) | | wez_launch_mixed | Multiple different CLIs in one tab | | wez_launch_grid | Manual grid of panes (rows × cols) | | wez_spawn | New window/tab with optional CLI or command | | wez_split | Split a pane (right/bottom) with optional CLI |

Text I/O

| Tool | Description | |---|---| | wez_send_text | Type text into a pane (no Enter) | | wez_send_text_submit | Type text + Enter (primary method for injecting prompts) | | wez_send_text_all | Different text to each pane in a tab | | wez_send_text_submit_all | Broadcast same text to all panes in a tab | | wez_send_text_submit_some | Send text to specific pane IDs | | wez_get_text | Read text from a pane (supports scrollback) |

Reading & Monitoring

| Tool | Description | |---|---| | wez_read_all | Quick passive read of ALL panes — fast, never interrupts | | wez_read_all_deep | Deep read — prompts idle agents for status summaries | | wez_read_tab | Read all panes in a specific tab | | wez_screenshot | Screenshot the active Wezterm window | | wez_screenshot_all_tabs | Screenshot each tab |

Special Keys

| Tool | Description | |---|---| | wez_send_key | Send ctrl+c, ctrl+d, escape, enter, arrow keys, etc. | | wez_send_key_all | Send a key to all panes in a tab |

Navigation & Layout

| Tool | Description | |---|---| | wez_focus_pane | Focus a pane by ID | | wez_focus_direction | Focus Up/Down/Left/Right | | wez_focus_tab | Switch to tab by index | | wez_resize_pane | Resize a pane | | wez_zoom_pane | Toggle zoom (maximize/restore) | | wez_move_to_tab | Move a pane into its own tab | | wez_fullscreen | Toggle fullscreen |

Titles & Workspace

| Tool | Description | |---|---| | wez_set_tab_title | Set a tab's title | | wez_set_window_title | Set a window's title | | wez_rename_workspace | Rename a workspace |

Pane Management

| Tool | Description | |---|---| | wez_kill_pane | Close a single pane | | wez_kill_tab | Kill all panes in a tab | | wez_kill_all | Full shutdown (panes + GUI + mux + sockets) | | wez_kill_gui | Kill GUI process only | | wez_kill_mux | Kill mux-server only | | wez_clean_sockets | Remove stale socket files | | wez_restart_pane | Kill + relaunch same CLI in place |

Session Recovery

| Tool | Description | |---|---| | wez_session_save | Save state (windows, tabs, panes, CLIs, session IDs) to manifest | | wez_session_recover | Recreate full layout from manifest, resume each CLI session | | wez_reconcile | Compare manifest vs live state, report drift |

Session Recovery — How It Works

Session ID Capture

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

| CLI | Session ID Source | |---|---| | Claude | ~/.claude/projects/{encoded}/ → session .jsonl files | | Gemini | ~/.gemini/projects.json → slug → chats directory | | Codex | ~/.codex/sessions/ → rollout .jsonl files | | OpenCode | SQLite DB → session table with directory column | | Goose | goose session list --format json |

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:

| Concern | Linux | macOS | Windows | |---|---|---|---| | Socket dir | /run/user/{uid}/wezterm | ~/.local/share/wezterm | ~/.local/share/wezterm | | WezTerm binary | PATH | /Applications/WezTerm.app/... | Program Files\WezTerm\ | | Screenshot | import/scrot/grim/gnome-screenshot | screencapture | PowerShell | | Process mgmt | pgrep/pkill | pgrep/pkill | tasklist/taskkill | | Enter key | CR (PTY translates to LF) | CR | LF (ConPTY) | | Shell | bash | bash | cmd.exe | | CLI wrapping | direct exec | direct exec | cmd.exe /c (npm shims) |

Testing

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

| Test | Focus | |---|---| | recovery-test.md | Full session recovery (7 windows, 22 panes, 14 CLI agents) | | 01-startup-status.md | Status, list, start | | 02-spawn-split-read.md | Spawn, split, get_text | | 03-input-methods.md | send_text, send_text_submit, send_key | | 04-bulk-input.md | Broadcast, per-pane, selective send | | 05-navigation.md | Focus pane, direction, tab | | 06-layout.md | Resize, zoom, move_to_tab, fullscreen | | 07-titles-workspace.md | Tab/window titles, workspace rename | | 08-reading-screenshots.md | read_tab, read_all, read_all_deep, screenshots | | 09-lifecycle.md | kill_pane, kill_tab, restart_pane, kill_gui/mux | | 10-launchers-sessions.md | launch_agents, launch_grid, launch_mixed, save/recover |

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.