wezterm-agent-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,107 @@
+# PolyForm Strict License 1.0.0
+
+<https://polyformproject.org/licenses/strict/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose, other than distributing
+the software or making changes or new works based on the
+software.
+
+## Patent License
+
+The licensor grants you a patent license for the software
+that covers patent claims the licensor can license, or
+becomes able to license, that you would infringe by using
+the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or
+religious observance, without any anticipated commercial
+application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational
+institution, public research organization, public safety
+or health organization, environmental protection
+organization, or government institution is use for a
+permitted purpose regardless of the source of funding or
+obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under
+the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer
+any of your licenses to anyone else, or prevent the
+licensor from granting licenses to anyone else. These
+terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes
+or contributes to infringement of any patent, your patent
+license for the software granted under these terms ends
+immediately. If your company makes such a claim, your
+patent license ends immediately for work on behalf of
+your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the
+software not covered by your licenses, your licenses can
+nonetheless continue if you come into full compliance
+with these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice.
+
+## No Liability
+
+***As far as the law allows, the software comes as is,
+without any warranty or condition, and the licensor will
+not be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering
+these terms, and the **software** is the software the
+licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to
+these terms.
+
+**Your company** is any legal entity, sole
+proprietorship, or other kind of organization that you
+work for, plus all organizations that have control over,
+are under the control of, or are under common control
+with that organization. **Control** means ownership of
+substantially all the assets of an entity, or the power
+to direct its management and policies by vote, contract,
+or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for
+the software under these terms.
+
+**Use** means anything you do with the software requiring
+one of your licenses.

package/README.md

@@ -0,0 +1,288 @@
+# wezterm-mcp
+
+Wezterm MCP Server — a programmable terminal control plane for multi-agent AI workflows.
+
+Turns [Wezterm](https://wezfurlong.org/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 Claude agents for the auth-service project"│
+│                         │                           │
+│                    MCP Tool Calls                   │
+│                         │                           │
+├─────────────────────────┼───────────────────────────┤
+│                  wezterm-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│  │  │          │  │          │          │
+│  │ └──┴──┘  │  │          │  │          │          │
+│  └──────────┘  └──────────┘  └──────────┘          │
+└─────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (v18+)
+- [Wezterm](https://wezfurlong.org/wezterm/installation)
+
+### Setup
+
+```bash
+git clone https://github.com/multiagentcognition/wezterm-mcp.git
+cd wezterm-mcp
+npm install
+npm run build
+```
+
+### Wezterm Lua Config
+
+Copy `wezterm.lua` to your Wezterm config directory:
+
+```bash
+# Linux
+cp wezterm.lua ~/.config/wezterm/wezterm.lua
+
+# macOS
+cp wezterm.lua ~/.config/wezterm/wezterm.lua
+
+# Windows
+copy wezterm.lua %USERPROFILE%\.config\wezterm\wezterm.lua
+```
+
+It provides:
+- **Auto-maximize** on startup
+- **Window titles** derived from project directory
+- **N/M numbering** for multiple windows of the same project
+- **Tab titles** auto-derived from pane CLI contents (e.g., "Claude (3) + shell")
+- **F11** toggles fullscreen
+
+## Configuration
+
+Add to your MCP client config (e.g., `.mcp.json`, Claude Code settings, etc.):
+
+```json
+{
+  "mcpServers": {
+    "wezterm": {
+      "command": "node",
+      "args": ["/path/to/wezterm-mcp/build/wez-mcp.js"],
+      "env": {
+        "WEZ_PROJECT_ROOT": "/path/to/your/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](https://polyformproject.org/licenses/strict/1.0.0) — personal and non-commercial use only. No modifications, no commercial/enterprise use. See [LICENSE](LICENSE) for full terms.

package/build/platform.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Platform abstraction layer for Wezterm MCP Server.
+ *
+ * Centralises all OS-specific behaviour so the main code never
+ * branches on IS_WIN / IS_MAC.  Three concrete implementations
+ * share a Unix base; Linux and macOS override where they differ.
+ */
+declare function sleepMs(ms: number): void;
+export interface Platform {
+    readonly name: 'linux' | 'macos' | 'windows';
+    weztermBin(): string;
+    weztermGuiBin(): string;
+    isWezInstalled(): boolean;
+    isProcessRunning(name: string): boolean;
+    killProcess(name: string): void;
+    socketDir(): string;
+    /** Value for execSync's `shell` option. */
+    readonly shell: string | true;
+    /** Default interactive shell binary (bash / cmd.exe). */
+    readonly defaultShell: string;
+    /** Wrap a command string for shell execution → [shell, flag, cmd]. */
+    shellExec(cmd: string): string[];
+    /** Syntax for setting an env var inline: 'KEY=val' (unix) / 'set KEY=val' (win). */
+    setEnvCmd(key: string, val: string): string;
+    /** Build a shell command with env var prefixes: 'K=v cmd' (unix) / 'set K=v && cmd' (win). */
+    envShellCommand(envParts: string[], cmd: string): string;
+    /** Character to send as Enter keypress. CR on Unix (PTY icrnl translates to LF), LF on Windows (ConPTY has no icrnl). */
+    readonly enterKey: string;
+    /** Cross-platform synchronous sleep. */
+    sleep(seconds: number): void;
+    /** Find the PID of a CLI binary running on a given TTY/pane. */
+    getCliPid(ttyName: string, binName: string): string | null;
+    /** Return both slash variants of a path (forward + backslash). Single-item on Unix. */
+    pathVariants(cwd: string): string[];
+    /** Normalise a file:// URI (as returned by wezterm list) to a local path. */
+    normalizeCwd(raw: string): string;
+    /** Encode a cwd for Claude's trust directory name. */
+    encodeTrustPath(cwd: string): string;
+    /** Strip trailing path separator(s). */
+    stripTrailingSep(p: string): string;
+    /**
+     * On Windows npm-installed CLIs use .cmd wrappers that wezterm cannot exec
+     * directly — wrap them in cmd.exe.  On Unix this is a no-op pass-through.
+     * Returns { parts, shellCommand, needsShell }.
+     */
+    wrapCliForSpawn(cli: string, parts: string[]): {
+        parts: string[];
+        shellCommand: string;
+        needsShell: boolean;
+    };
+    screenshotCmds(filePath: string): string[];
+    readonly screenshotErrorMsg: string;
+    toggleFullscreen(): void;
+    readonly fullscreenErrorMsg: string;
+}
+export declare const OS: Platform;
+export { sleepMs };