Wezterm Agent Mcp — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Wezterm Agent Mcp (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
+---------------------------------------------------+
| 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| | | | | | |
| | +--+--+ | | | | | |
| +-----------+ +-----------+ +-----------+ |
+---------------------------------------------------+One command:
npm install -g wezterm-agent-mcpInstall 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)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.luagit 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| 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 |
| 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.
| 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 |
| 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 |
| 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) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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 |
--resume <id> or falls back to --continueAll 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) |
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.
format-window-title callback parameter types vary between versions.wez_read_all_deep waits up to 30 seconds per idle agent.wez_kill_all, use wez_start before spawning new panes.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:
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.
PolyForm Strict 1.0.0 — personal and non-commercial use only. No modifications, no commercial/enterprise use. See LICENSE for full terms.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.