@wong2kim/wmux 1.1.2 → 2.0.1

package/README.md

@@ -1,112 +1,158 @@
-# wmux
+# wmux — AI Agent Terminal for Windows
 
-**AI Agent Terminal for Windows**
+> **Run Claude Code + Codex + Gemini CLI side by side.**
+> Split terminals, browser automation, MCP integration — the only proper way to use AI agents on Windows.
 
-Run Claude Code, Codex, Gemini CLI side by side — with built-in browser, smart notifications, and MCP integration.
+[![Windows 10/11](https://img.shields.io/badge/Windows-10%2F11-0078D6?logo=windows&logoColor=white)](https://github.com/openwong2kim/wmux/releases/latest)
+[![npm](https://img.shields.io/npm/v/@wong2kim/wmux?color=CB3837&logo=npm)](https://www.npmjs.com/package/@wong2kim/wmux)
+[![Electron 41](https://img.shields.io/badge/Electron-41-47848F?logo=electron&logoColor=white)](https://www.electronjs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/openwong2kim/wmux?style=social)](https://github.com/openwong2kim/wmux)
 
-Inspired by [cmux](https://github.com/manaflow-ai/cmux) (macOS), wmux brings the same philosophy to Windows: **a primitive, not a solution.** Composable building blocks for multi-agent workflows.
+---
+
+## Still using one terminal for your AI coding agents on Windows?
+
+macOS has [cmux](https://github.com/manaflow-ai/cmux) — a tmux-based terminal multiplexer for AI agents.
+
+**Windows has no tmux.** Without WSL, there was no way.
 
-![Windows](https://img.shields.io/badge/Windows-10%2F11-0078D6?logo=windows)
-![Electron](https://img.shields.io/badge/Electron-41-47848F?logo=electron)
-![License](https://img.shields.io/badge/License-MIT-green)
+wmux fixes this. Native Windows terminal multiplexer + browser automation + MCP server. Your AI agent reads the terminal, controls the browser, and works autonomously.
+
+```
+Claude Code writes the backend on the left
+Codex builds the frontend on the right
+Gemini CLI runs tests at the bottom
+— all on one screen, simultaneously.
+```
 
 ---
 
-## Install
+## Install in 30 seconds
+
+**Installer:**
 
-**Download:** [wmux-1.1.2 Setup.exe](https://github.com/openwong2kim/wmux/releases/latest)
+[Download wmux Setup.exe](https://github.com/openwong2kim/wmux/releases/latest)
 
-Or build from source:
+**One-liner (PowerShell):**
 ```powershell
 irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex
 ```
 
+**npm (CLI + MCP server):**
+```bash
+npm install -g @wong2kim/wmux
+```
+
 ---
 
 ## Why wmux?
 
-| Problem | wmux |
-|---------|------|
-| Windows has no cmux | Native Windows terminal multiplexer for AI agents |
-| Agents can't see the browser | Built-in browser with MCP — Claude clicks, fills, evaluates JS |
-| "Is it done yet?" | Smart activity-based notifications + taskbar flash |
-| Can't compare agents | Multiview — Ctrl+click workspaces to view side by side |
-| Hard to describe UI elements to LLM | Inspector — click any element, LLM-friendly context copied |
+### 1. Your AI agent controls the browser — for real
+
+Tell Claude Code "search Google for this" and it actually does it.
+
+wmux's built-in browser connects via Chrome DevTools Protocol. Click, type, screenshot, execute JS — all done by the AI directly. Works perfectly with React controlled inputs and CJK text.
+
+```
+You: "Search for wmux on Google"
+Claude: browser_open → browser_snapshot → browser_fill(ref=13, "wmux") → browser_press_key("Enter")
+→ Actually searches Google. Done.
+```
+
+### 2. Multiple terminals in one window
+
+`Ctrl+D` to split, `Ctrl+N` for new workspace. Place multiple terminals and browsers in each workspace. `Ctrl+click` for multiview — see multiple workspaces at once.
+
+ConPTY-based native Windows terminal. xterm.js + WebGL hardware-accelerated rendering. 999K lines of scrollback. Terminal content persists even after restart.
+
+### 3. No more asking "is it done yet?"
+
+wmux tells you when your AI agent finishes.
+
+- Task complete → desktop notification + taskbar flash
+- Abnormal exit → immediate warning
+- `git push --force`, `rm -rf`, `DROP TABLE` → dangerous action detection
+
+Not pattern matching — output throughput-based detection. Works with any agent.
+
+### 4. Automatic Claude Code integration
+
+Launch wmux and the MCP server registers automatically. Claude Code just works:
+
+| What Claude can do | MCP Tool |
+|---|---|
+| Open browser | `browser_open` |
+| Navigate to URL | `browser_navigate` |
+| Take screenshot | `browser_screenshot` |
+| Read page structure | `browser_snapshot` |
+| Click element | `browser_click` |
+| Fill form | `browser_fill` / `browser_type` |
+| Execute JS | `browser_evaluate` |
+| Press key | `browser_press_key` |
+| Read terminal | `terminal_read` |
+| Send command | `terminal_send` |
+| Manage workspaces | `workspace_list` / `surface_list` / `pane_list` |
+
+**Multi-agent:** Every browser tool accepts `surfaceId` — each Claude Code session controls its own browser independently.
+
+### 5. Security that actually matters
+
+- Token authentication on all IPC pipes
+- SSRF protection — blocks private IPs, `file://`, `javascript:` schemes
+- PTY input sanitization — prevents command injection
+- Randomized CDP port — no fixed debug port
+- Memory pressure watchdog — reaps dead sessions at 750MB, blocks new ones at 1GB
+- Electron Fuses — RunAsNode disabled, cookie encryption enabled
 
 ---
 
-## Features
+## All Features
 
 ### Terminal
-- **xterm.js + WebGL** GPU-accelerated rendering
-- **ConPTY** native Windows pseudo-terminal
-- **Split panes** — `Ctrl+D` horizontal, `Ctrl+Shift+D` vertical
-- **Tabs** — multiple surfaces per pane
-- **Vi copy mode** — `Ctrl+Shift+X`
-- **Search** — `Ctrl+F`
-- **Unlimited scrollback** — 999,999 lines default
-- **Scrollback persistence** — terminal content saved to disk, restored on restart
+- xterm.js + WebGL GPU-accelerated rendering
+- ConPTY native Windows pseudo-terminal
+- Split panes — `Ctrl+D` horizontal, `Ctrl+Shift+D` vertical
+- Tabs — multiple surfaces per pane
+- Vi copy mode — `Ctrl+Shift+X`
+- Search — `Ctrl+F`
+- 999K line scrollback with disk persistence
 
 ### Workspaces
 - Sidebar with drag-and-drop reordering
-- `Ctrl+1` ~ `Ctrl+9` quick switch
-- **Multiview** — `Ctrl+click` workspaces to split-view them simultaneously
-- `Ctrl+Shift+G` to exit multiview
-- **Session persistence** — workspace layout, tabs, cwd, and terminal scrollback all restored on restart
+- `Ctrl+1~9` quick switch
+- Multiview — `Ctrl+click` to view multiple workspaces side by side
+- Full session persistence — layout, tabs, cwd, scrollback all restored
+- One-click reset in Settings
 
-### Browser
+### Browser + CDP Automation
 - Built-in browser panel — `Ctrl+Shift+L`
 - Navigation bar, DevTools, back/forward
-- **Element Inspector** — magnifying glass button to inspect elements
-  - Hover to highlight, click to copy LLM-friendly context:
-    ```
-    [Inspector] Google (https://www.google.com/)
-    selector: input.gLFyf
-    <input type="text" name="q" aria-label="Search">
-    text: ""
-    parent: div.RNNXgb > siblings: button"Google Search", button"I'm Feeling Lucky"
-    ```
-  - Paste directly into Claude — it understands the element immediately
+- Element Inspector — hover to highlight, click to copy LLM-friendly context
+- Full CDP automation: click, fill, type, screenshot, JS eval, key press
 
 ### Notifications
-- **Activity-based detection** — monitors output throughput, no fragile pattern matching
-- **Taskbar flash** — orange flash when notifications arrive while unfocused
-- **Windows toast** — native OS notification with click-to-focus
-- **Process exit alerts** — notifies on non-zero exit codes
-- **Notification panel** — `Ctrl+I`, read/unread tracking, per-workspace filtering
-- **Sound** — Web Audio synthesized tones per notification type
-
-### MCP Server (Claude Code Integration)
-wmux automatically registers its MCP server when launched. Claude Code can:
-
-| Tool | What it does |
-|------|-------------|
-| `browser_open` | Open a new browser panel |
-| `browser_navigate` | Go to URL |
-| `browser_snapshot` | Get full page HTML |
-| `browser_click` | Click element by CSS selector |
-| `browser_fill` | Fill input field |
-| `browser_eval` | Execute JavaScript |
-| `terminal_read` | Read terminal screen |
-| `terminal_send` | Send text to terminal |
-| `terminal_send_key` | Send key (enter, ctrl+c, etc.) |
-| `workspace_list` | List all workspaces |
-| `surface_list` | List surfaces |
-| `pane_list` | List panes |
-
-**Multi-agent:** All browser tools accept `surfaceId` — each Claude Code session controls its own browser independently.
-
-### Agent Status Detection
-Gate-based detection for AI coding agents:
-- Claude Code, Cursor, Aider, Codex CLI, Gemini CLI, OpenCode, GitHub Copilot CLI
-- Detects agent startup → activates monitoring
-- Critical action warnings (git push --force, rm -rf, DROP TABLE, etc.)
+- Output throughput-based activity detection
+- Taskbar flash + Windows toast notifications
+- Process exit alerts
+- Notification panel — `Ctrl+I`
+- Web Audio sound effects
+
+### Agent Detection
+Claude Code, Cursor, Aider, Codex CLI, Gemini CLI, OpenCode, GitHub Copilot CLI
+- Detects agent start → activates monitoring
+- Critical action warnings
+
+### Daemon Process
+- Background session management (survives app restart)
+- Scrollback buffer dump and auto-recovery
+- Dead session TTL reaping (24h default)
 
 ### Themes
 Catppuccin, Tokyo Night, Dracula, Nord, Gruvbox, Solarized, One Dark, and more.
 
 ### i18n
-English, 한국어, 日本語, 中文
+English, Korean, Japanese, Chinese
 
 ---
 
@@ -120,7 +166,7 @@ English, 한국어, 日本語, 中文
 | `Ctrl+W` | Close tab |
 | `Ctrl+N` | New workspace |
 | `Ctrl+1~9` | Switch workspace |
-| `Ctrl+click` | Add workspace to multiview |
+| `Ctrl+click` | Add to multiview |
 | `Ctrl+Shift+G` | Exit multiview |
 | `Ctrl+Shift+L` | Open browser |
 | `Ctrl+B` | Toggle sidebar |
@@ -129,8 +175,6 @@ English, 한국어, 日本語, 中文
 | `Ctrl+,` | Settings |
 | `Ctrl+F` | Search terminal |
 | `Ctrl+Shift+X` | Vi copy mode |
-| `Ctrl+Shift+H` | Flash pane |
-| `Alt+Ctrl+Arrow` | Focus adjacent pane |
 | `F12` | Browser DevTools |
 
 ---
@@ -159,7 +203,7 @@ npm start           # Dev mode
 npm run make        # Build installer
 ```
 
-### Requirements (development only)
+### Requirements (dev only)
 - Node.js 18+
 - Python 3.x (for node-gyp)
 - Visual Studio Build Tools with C++ workload
@@ -176,37 +220,44 @@ Electron Main Process
 ├── PTYBridge (data forwarding + ActivityMonitor)
 ├── AgentDetector (gate-based agent status)
 ├── SessionManager (atomic save with .bak recovery)
-├── ScrollbackPersistence (dump/load terminal buffers)
-├── PipeServer (Named Pipe JSON-RPC)
+├── ScrollbackPersistence (terminal buffer dump/load)
+├── PipeServer (Named Pipe JSON-RPC + token auth)
 ├── McpRegistrar (auto-registers MCP in ~/.claude.json)
-├── DaemonClient (optional daemon mode connector)
+├── WebviewCdpManager (CDP proxy to <webview>)
+├── DaemonClient (daemon mode connector)
 └── ToastManager (OS notifications + taskbar flash)
 
 Renderer Process (React 19 + Zustand)
 ├── PaneContainer (recursive split layout)
 ├── Terminal (xterm.js + WebGL + scrollback restore)
-├── BrowserPanel (webview + Inspector)
+├── BrowserPanel (webview + Inspector + CDP)
 ├── NotificationPanel
+├── SettingsPanel (workspace reset)
 └── Multiview grid
 
-Daemon Process (optional, standalone)
+Daemon Process (standalone)
 ├── DaemonSessionManager (ConPTY lifecycle)
 ├── RingBuffer (circular scrollback buffer)
 ├── StateWriter (session suspend/resume)
-└── DaemonPipeServer (Named Pipe RPC)
+├── ProcessMonitor (external process watchdog)
+├── Watchdog (memory pressure escalation)
+└── DaemonPipeServer (Named Pipe RPC + token auth)
 
 MCP Server (stdio)
-└── Bridges Claude Code ↔ wmux via Named Pipe RPC
+├── PlaywrightEngine (CDP connection, fast-fail)
+├── CDP RPC fallback (screenshot, evaluate, type, click)
+└── Claude Code <-> wmux Named Pipe RPC bridge
 ```
 
 ---
 
 ## Acknowledgments
 
-- [cmux](https://github.com/manaflow-ai/cmux) — The macOS AI agent terminal that inspired wmux. Same philosophy: primitives over prescriptive workflows.
+- [cmux](https://github.com/manaflow-ai/cmux) — The macOS AI agent terminal that inspired wmux
 - [xterm.js](https://xtermjs.org/) — Terminal rendering
 - [node-pty](https://github.com/microsoft/node-pty) — Pseudo-terminal
 - [Electron](https://www.electronjs.org/) — Desktop framework
+- [Playwright](https://playwright.dev/) — Browser automation engine
 
 ---
 

package/dist/cli/cli/commands/system.js

@@ -1,8 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleSystem = handleSystem;
+const fs_1 = require("fs");
+const path_1 = require("path");
 const client_1 = require("../client");
 const utils_1 = require("../utils");
+function getFallbackVersion() {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', '..', 'package.json'), 'utf-8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 async function handleSystem(cmd, args, jsonMode) {
     let response;
     switch (cmd) {
@@ -18,7 +29,7 @@ async function handleSystem(cmd, args, jsonMode) {
                 }
                 const info = response.result;
                 console.log(`app:      ${info?.app ?? 'wmux'}`);
-                console.log(`version:  ${info?.version ?? '1.0.0'}`);
+                console.log(`version:  ${info?.version ?? getFallbackVersion()}`);
                 console.log(`platform: ${info?.platform ?? process.platform}`);
             }
             break;

package/dist/cli/shared/rpc.js

@@ -34,6 +34,12 @@ exports.ALL_RPC_METHODS = [
     'browser.type.humanlike',
     'browser.cdp.target',
     'browser.cdp.info',
+    'browser.cdp.send',
+    'browser.screenshot',
+    'browser.evaluate',
+    'browser.type.cdp',
+    'browser.click.cdp',
+    'browser.press.cdp',
     'daemon.createSession',
     'daemon.destroySession',
     'daemon.attachSession',

package/dist/cli/shared/types.js

@@ -7,19 +7,22 @@ exports.validateMessage = validateMessage;
 exports.createSurface = createSurface;
 exports.createLeafPane = createLeafPane;
 exports.createWorkspace = createWorkspace;
+exports.validateNavigationUrl = validateNavigationUrl;
 // === Utility: generate unique IDs ===
 function generateId(prefix) {
     return `${prefix}-${crypto.randomUUID()}`;
 }
 // === Security: sanitize text before PTY write ===
 /**
- * Strips control characters (\r, \n, \x00-\x1f except \t) from text
- * that will be written to a PTY, preventing embedded command injection.
+ * Strips dangerous control characters from text before writing to a PTY.
+ * Removes: NULL byte (\x00) and C1 control characters (\x80-\x9f).
+ * Preserves: CR (\r), LF (\n), Tab (\t), ESC sequences (\x1b[...),
+ * and other standard terminal control characters needed for normal operation.
  */
 function sanitizePtyText(text) {
-    // Remove all control chars except tab (\x09)
+    // Remove NULL byte and C1 control characters (U+0080–U+009F)
     // eslint-disable-next-line no-control-regex
-    return text.replace(/[\x00-\x08\x0a-\x1f\x7f\u0080-\u009f]/g, '');
+    return text.replace(/[\x00\u0080-\u009f]/g, '');
 }
 /**
  * Validates and clamps a user-supplied name string.
@@ -77,3 +80,104 @@ function createWorkspace(name) {
         activePaneId: rootPane.id,
     };
 }
+// === Security: URL validation for SSRF prevention ===
+/**
+ * Validates a URL for safe navigation. Blocks dangerous schemes and private
+ * network addresses to prevent SSRF attacks from AI agent-driven browsing.
+ *
+ * Allows localhost/127.0.0.1/[::1] for local development servers.
+ *
+ * NOTE (v1 limitation): This is string-based validation only. DNS-resolved IPs
+ * are not checked, so DNS rebinding attacks are not mitigated. A future version
+ * should resolve hostnames and re-validate the resolved IP.
+ */
+function validateNavigationUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { valid: false, reason: 'Invalid URL' };
+    }
+    // Only allow http and https schemes
+    const scheme = parsed.protocol.toLowerCase();
+    if (scheme !== 'http:' && scheme !== 'https:') {
+        return { valid: false, reason: `Blocked URL scheme: ${scheme}` };
+    }
+    // Extract hostname (strip brackets from IPv6)
+    const hostname = parsed.hostname.toLowerCase();
+    // Allow localhost and IPv4/IPv6 loopback
+    if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+        return { valid: true };
+    }
+    // Block IPv6 private/link-local ranges
+    if (hostname.startsWith('[') || hostname.includes(':')) {
+        // Hostname is an IPv6 address (URL parser strips brackets in .hostname)
+        const addr = hostname;
+        // Block fc00::/7 (unique local) — starts with fc or fd
+        if (addr.startsWith('fc') || addr.startsWith('fd')) {
+            return { valid: false, reason: 'Blocked private IPv6 address (fc00::/7)' };
+        }
+        // Block fe80::/10 (link-local) — starts with fe8, fe9, fea, feb
+        if (/^fe[89ab]/.test(addr)) {
+            return { valid: false, reason: 'Blocked link-local IPv6 address (fe80::/10)' };
+        }
+        // ::1 already allowed above; block any other loopback representation
+        // Normalize: collapse :: and check
+        if (addr === '0:0:0:0:0:0:0:1' || addr === '0000:0000:0000:0000:0000:0000:0000:0001') {
+            return { valid: true };
+        }
+        // Block null IPv6 address (:: or 0:0:0:0:0:0:0:0) — equivalent to 0.0.0.0
+        if (addr === '::' || addr === '0:0:0:0:0:0:0:0' || addr === '0000:0000:0000:0000:0000:0000:0000:0000') {
+            return { valid: false, reason: 'Blocked null IPv6 address (equivalent to 0.0.0.0)' };
+        }
+        // Block IPv4-mapped IPv6 (::ffff:x.x.x.x) and IPv4-compatible IPv6 (::x.x.x.x)
+        // These resolve to their embedded IPv4 address, bypassing IPv4 private IP checks.
+        const v4MappedMatch = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(addr);
+        const v4CompatMatch = !v4MappedMatch ? /^::(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(addr) : null;
+        const embeddedV4 = v4MappedMatch?.[1] ?? v4CompatMatch?.[1];
+        if (embeddedV4) {
+            // Recursively validate the embedded IPv4 through the same checks
+            const embeddedResult = validateNavigationUrl(`http://${embeddedV4}/`);
+            if (!embeddedResult.valid) {
+                return { valid: false, reason: `Blocked IPv4-mapped/compatible IPv6: embedded ${embeddedV4} — ${embeddedResult.reason}` };
+            }
+        }
+        return { valid: true };
+    }
+    // Check for IPv4 addresses
+    const ipv4Match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
+    if (ipv4Match) {
+        const octets = [
+            parseInt(ipv4Match[1], 10),
+            parseInt(ipv4Match[2], 10),
+            parseInt(ipv4Match[3], 10),
+            parseInt(ipv4Match[4], 10),
+        ];
+        // 127.0.0.1 already allowed above; block other 127.x.x.x
+        if (octets[0] === 127) {
+            return { valid: false, reason: 'Blocked loopback address' };
+        }
+        // Block 10.0.0.0/8
+        if (octets[0] === 10) {
+            return { valid: false, reason: 'Blocked private IP address (10.0.0.0/8)' };
+        }
+        // Block 172.16.0.0/12 (172.16.x.x – 172.31.x.x)
+        if (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) {
+            return { valid: false, reason: 'Blocked private IP address (172.16.0.0/12)' };
+        }
+        // Block 192.168.0.0/16
+        if (octets[0] === 192 && octets[1] === 168) {
+            return { valid: false, reason: 'Blocked private IP address (192.168.0.0/16)' };
+        }
+        // Block 169.254.0.0/16 (link-local, includes cloud metadata 169.254.169.254)
+        if (octets[0] === 169 && octets[1] === 254) {
+            return { valid: false, reason: 'Blocked link-local/cloud metadata address (169.254.0.0/16)' };
+        }
+        // Block 0.0.0.0
+        if (octets.every((o) => o === 0)) {
+            return { valid: false, reason: 'Blocked null address (0.0.0.0)' };
+        }
+    }
+    return { valid: true };
+}

package/dist/mcp/mcp/index.js

@@ -14,9 +14,20 @@ const wait_1 = require("./playwright/tools/wait");
 const file_1 = require("./playwright/tools/file");
 const utility_1 = require("./playwright/tools/utility");
 const extraction_1 = require("./playwright/tools/extraction");
+const fs_1 = require("fs");
+const path_1 = require("path");
+function getVersion() {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', '..', 'package.json'), 'utf-8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 const server = new mcp_js_1.McpServer({
     name: 'wmux',
-    version: '1.0.0',
+    version: getVersion(),
 });
 // Helper: wrap an RPC call as an MCP tool result
 async function callRpc(method, params = {}) {