@wong2kim/wmux 1.0.0 → 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 openwong2kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,157 +1,209 @@
-# wmux
-
-> Terminal multiplexer for Windows with built-in browser, notifications, and AI agent status detection.
-
-Windows-native terminal multiplexer with workspaces, panes, tabs, integrated browser, notification system, CLI/API access, and session management.
-
-## Quick Install
-
-**PowerShell (recommended):**
-```powershell
-irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex
-```
-
-**Git Bash / WSL:**
-```bash
-curl -fsSL https://raw.githubusercontent.com/openwong2kim/wmux/main/install.sh | bash
-```
-
-**Manual:**
-```bash
-git clone https://github.com/openwong2kim/wmux.git
-cd wmux
-npm install
-npm start
-```
-
-## Requirements
-
-- Windows 10/11
-- Node.js 18+
-- Git
-
-## Features
-
-- **Terminal**: xterm.js + WebGL GPU rendering, ConPTY, PowerShell native
-- **Workspaces**: Vertical sidebar, drag-and-drop, Ctrl+1~9 switching
-- **Split Panes**: Ctrl+D / Ctrl+Shift+D, directional focus
-- **In-App Browser**: Ctrl+Shift+L, scriptable API
-- **Notifications**: OSC 9/99/777, rings, toast, Ctrl+I panel
-- **AI Agent Status**: Detects Claude Code, Cursor, Aider, Codex, Gemini, Copilot, OpenCode
-- **Command Palette**: Ctrl+K fuzzy search
-- **Terminal Search**: Ctrl+F
-- **Vi Copy Mode**: Ctrl+Shift+X
-- **CLI + API**: Named Pipe JSON-RPC, `wmux` CLI
-- **MCP Server**: Claude Code can control browser and terminal via MCP tools
-- **Multi-Agent**: Each agent targets its own browser surface via `surfaceId`
-- **Session Management**: Save and restore sessions
-- **i18n**: English, Korean, Japanese, Chinese
-
-## Usage
-
-```bash
-npm start              # Run in dev mode
-npm run package        # Build executable
-npm run make           # Create installer
-wmux --help            # CLI commands
-```
-
-## CLI Examples
-
-```bash
-# Workspace management
-wmux workspace create "MyWorkspace"
-wmux workspace list
-wmux workspace switch "MyWorkspace"
-
-# Pane operations
-wmux pane split-right
-wmux pane split-down
-wmux pane send-text "echo hello"
-
-# Surface (browser)
-wmux surface open "https://example.com"
-wmux surface eval "window.location"
-```
-
-## Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| Ctrl+B | Toggle sidebar |
-| Ctrl+N | New workspace |
-| Ctrl+D | Split right |
-| Ctrl+Shift+D | Split down |
-| Ctrl+T | New tab |
-| Ctrl+W | Close tab |
-| Ctrl+F | Search terminal |
-| Ctrl+K | Command palette |
-| Ctrl+I | Notifications |
-| Ctrl+, | Settings |
-| Ctrl+Shift+L | Open browser |
-| Ctrl+Shift+H | Flash pane |
-| Ctrl+1~9 | Switch workspace |
-
-## Tech Stack
-
-Electron 41 + React 19 + TypeScript 5.9 + Tailwind 3 + Zustand 5 + xterm.js 6 + node-pty
-
-## MCP Server (Claude Code Integration)
-
-wmux includes an MCP server that lets Claude Code directly control the browser and terminal.
-
-### Setup
-
-```bash
-npm run build:mcp
-```
-
-Add to your project's `.mcp.json`:
-```json
-{
-  "mcpServers": {
-    "wmux": {
-      "command": "node",
-      "args": ["<path-to-wmux>/dist/mcp/mcp/index.js"]
-    }
-  }
-}
-```
-
-`WMUX_SOCKET_PATH` and `WMUX_AUTH_TOKEN` are automatically set in wmux terminal sessions — no extra env config needed when running Claude Code inside wmux.
-
-### Available MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `browser_navigate` | Navigate browser to URL |
-| `browser_snapshot` | Get page HTML |
-| `browser_click` | Click element by CSS selector |
-| `browser_fill` | Fill input by CSS selector |
-| `browser_eval` | Execute JS in browser |
-| `terminal_read` | Read terminal screen |
-| `terminal_send` | Send text to terminal |
-| `terminal_send_key` | Send key (enter, ctrl+c, etc.) |
-| `workspace_list` | List workspaces |
-| `surface_list` | List surfaces (terminals + browsers) |
-| `pane_list` | List panes |
-
-### Multi-Agent Usage
-
-All browser tools accept an optional `surfaceId` parameter for multi-agent scenarios:
-
-```
-1. Call surface_list → find your browser surface ID
-2. Call browser_navigate with surfaceId="<your-browser-id>"
-3. Call browser_snapshot with surfaceId="<your-browser-id>"
-```
-
-Each agent can independently control its own browser surface. When `surfaceId` is omitted, the currently active browser surface is used.
-
-## Note on AI Agents
-
-WinMux detects AI coding agents for status display purposes only. It does not call any AI APIs, capture agent outputs, or automate agent interactions. Users are responsible for complying with their AI provider's Terms of Service.
-
-## License
-
-MIT
+# wmux
+
+**AI Agent Terminal for Windows**
+
+Run Claude Code, Codex, Gemini CLI side by side — with built-in browser, smart notifications, and MCP integration.
+
+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.
+
+![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)
+
+---
+
+## Install
+
+**Download:** [wmux-1.0.0 Setup.exe](https://github.com/openwong2kim/wmux/releases/latest)
+
+Or build from source:
+```powershell
+irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex
+```
+
+---
+
+## 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 |
+
+---
+
+## 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
+
+### 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 — everything restored on restart
+
+### Browser
+- 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
+
+### 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.)
+
+### Themes
+Catppuccin, Tokyo Night, Dracula, Nord, Gruvbox, Solarized, One Dark, and more.
+
+### i18n
+English, 한국어, 日本語, 中文
+
+---
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+D` | Split right |
+| `Ctrl+Shift+D` | Split down |
+| `Ctrl+T` | New tab |
+| `Ctrl+W` | Close tab |
+| `Ctrl+N` | New workspace |
+| `Ctrl+1~9` | Switch workspace |
+| `Ctrl+click` | Add workspace to multiview |
+| `Ctrl+Shift+G` | Exit multiview |
+| `Ctrl+Shift+L` | Open browser |
+| `Ctrl+B` | Toggle sidebar |
+| `Ctrl+K` | Command palette |
+| `Ctrl+I` | Notifications |
+| `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 |
+
+---
+
+## CLI
+
+```bash
+wmux workspace list
+wmux workspace create "backend"
+wmux pane split-right
+wmux pane send-text "npm test"
+wmux notify --title "Done" --body "Tests passed"
+wmux browser snapshot
+wmux browser click "#submit-btn"
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/openwong2kim/wmux.git
+cd wmux
+npm install
+npm start           # Dev mode
+npm run make        # Build installer
+```
+
+### Requirements (development only)
+- Node.js 18+
+- Python 3.x (for node-gyp)
+- Visual Studio Build Tools with C++ workload
+
+The `install.ps1` script auto-installs Python and VS Build Tools if missing.
+
+---
+
+## Architecture
+
+```
+Electron Main Process
+├── PTYManager (node-pty)
+├── PTYBridge (data forwarding + ActivityMonitor)
+├── AgentDetector (gate-based agent status)
+├── PipeServer (Named Pipe JSON-RPC)
+├── McpRegistrar (auto-registers MCP in ~/.claude.json)
+└── ToastManager (OS notifications + taskbar flash)
+
+Renderer Process (React 19 + Zustand)
+├── PaneContainer (recursive split layout)
+├── Terminal (xterm.js + WebGL)
+├── BrowserPanel (webview + Inspector)
+├── NotificationPanel
+└── Multiview grid
+
+MCP Server (stdio)
+└── Bridges Claude Code ↔ wmux via Named Pipe RPC
+```
+
+---
+
+## Acknowledgments
+
+- [cmux](https://github.com/manaflow-ai/cmux) — The macOS AI agent terminal that inspired wmux. Same philosophy: primitives over prescriptive workflows.
+- [xterm.js](https://xtermjs.org/) — Terminal rendering
+- [node-pty](https://github.com/microsoft/node-pty) — Pseudo-terminal
+- [Electron](https://www.electronjs.org/) — Desktop framework
+
+---
+
+## Note on AI Agents
+
+wmux detects AI coding agents for status display purposes only. It does not call any AI APIs, capture agent outputs, or automate agent interactions. Users are responsible for complying with their AI provider's Terms of Service.
+
+## License
+
+MIT

package/dist/cli/cli/client.js

@@ -37,7 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendRequest = sendRequest;
 const net = __importStar(require("net"));
 const crypto = __importStar(require("crypto"));
-const PIPE_NAME = process.env.WMUX_SOCKET_PATH || '\\\\.\\pipe\\wmux';
+const PIPE_NAME = process.env.WMUX_SOCKET_PATH || (process.platform === 'win32' ? '\\\\.\\pipe\\wmux' : '/tmp/wmux.sock');
 const TIMEOUT_MS = 5000;
 function sendRequest(method, params = {}) {
     return new Promise((resolve, reject) => {

package/dist/cli/cli/commands/browser.js

@@ -3,25 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleBrowser = handleBrowser;
 const client_1 = require("../client");
 const utils_1 = require("../utils");
-const BROWSER_HELP = `
-wmux browser — Scriptable Browser API
-
-USAGE
-  wmux browser <subcommand> [args]
-
-SUBCOMMANDS
-  snapshot                        Return the full page HTML (document.documentElement.outerHTML)
-  click <selector>                Click the first element matching the CSS selector
-  fill <selector> <text>          Set the value of an input matching the CSS selector
-  eval <code>                     Execute arbitrary JavaScript in the page context
-  navigate <url>                  Navigate the active browser surface to a URL
-
-EXAMPLES
-  wmux browser snapshot
-  wmux browser click "#submit-btn"
-  wmux browser fill "input[name=email]" "user@example.com"
-  wmux browser eval "document.title"
-  wmux browser navigate "https://example.com"
+const BROWSER_HELP = `
+wmux browser — Scriptable Browser API
+
+USAGE
+  wmux browser <subcommand> [args]
+
+SUBCOMMANDS
+  snapshot                        Return the full page HTML (document.documentElement.outerHTML)
+  click <selector>                Click the first element matching the CSS selector
+  fill <selector> <text>          Set the value of an input matching the CSS selector
+  eval <code>                     Execute arbitrary JavaScript in the page context
+  navigate <url>                  Navigate the active browser surface to a URL
+
+EXAMPLES
+  wmux browser snapshot
+  wmux browser click "#submit-btn"
+  wmux browser fill "input[name=email]" "user@example.com"
+  wmux browser eval "document.title"
+  wmux browser navigate "https://example.com"
 `.trimStart();
 async function handleBrowser(args, jsonMode) {
     const sub = args[0];

package/dist/cli/cli/index.js

@@ -12,64 +12,64 @@ const input_1 = require("./commands/input");
 const notify_1 = require("./commands/notify");
 const system_1 = require("./commands/system");
 const browser_1 = require("./commands/browser");
-const HELP_TEXT = `
-wmux CLI
-
-USAGE
-  wmux <command> [options]
-
-WORKSPACE COMMANDS
-  list-workspaces                   List all workspaces
-  new-workspace [--name <name>]     Create a new workspace
-  focus-workspace <id>              Focus a workspace by ID
-  close-workspace <id>              Close a workspace by ID
-  current-workspace                 Show the active workspace
-
-SURFACE COMMANDS
-  list-surfaces                     List all surfaces in the active workspace
-  new-surface                       Open a new surface (terminal tab)
-  focus-surface <id>                Focus a surface by ID
-  close-surface <id>                Close a surface by ID
-
-PANE COMMANDS
-  list-panes                        List all panes in the active workspace
-  focus-pane <id>                   Focus a pane by ID
-  split [--direction right|down]    Split the active pane (default: right)
-
-INPUT COMMANDS
-  send <text>                       Send text to the active terminal
-  send-key <keystroke>              Send a key (e.g. Enter, ctrl-c, Tab)
-  read-screen                       Read the current terminal screen content
-
-NOTIFICATION COMMANDS
-  notify --title <title> --body <body>   Show a notification in wmux
-
-SYSTEM COMMANDS
-  set-status <text>                 Set a status message on the active workspace
-  set-progress <0-100>              Set a progress value on the active workspace
-  identify                          Show wmux app info
-  capabilities                      List all supported RPC methods
-
-BROWSER COMMANDS
-  browser snapshot                  Return the full page HTML of the active browser surface
-  browser click <selector>          Click an element by CSS selector
-  browser fill <selector> <text>    Fill an input field by CSS selector
-  browser eval <code>               Execute JavaScript in the browser context
-  browser navigate <url>            Navigate the browser surface to a URL
-
-GLOBAL FLAGS
-  --json      Output raw JSON (useful for scripting)
-  --help      Show this help text
-
-EXAMPLES
-  wmux list-workspaces
-  wmux new-workspace --name dev
-  wmux send "echo hello"
-  wmux notify --title "Done" --body "Build finished"
-  wmux identify --json
-  wmux browser snapshot
-  wmux browser navigate "https://example.com"
-  wmux browser click "#login-btn"
+const HELP_TEXT = `
+wmux CLI
+
+USAGE
+  wmux <command> [options]
+
+WORKSPACE COMMANDS
+  list-workspaces                   List all workspaces
+  new-workspace [--name <name>]     Create a new workspace
+  focus-workspace <id>              Focus a workspace by ID
+  close-workspace <id>              Close a workspace by ID
+  current-workspace                 Show the active workspace
+
+SURFACE COMMANDS
+  list-surfaces                     List all surfaces in the active workspace
+  new-surface                       Open a new surface (terminal tab)
+  focus-surface <id>                Focus a surface by ID
+  close-surface <id>                Close a surface by ID
+
+PANE COMMANDS
+  list-panes                        List all panes in the active workspace
+  focus-pane <id>                   Focus a pane by ID
+  split [--direction right|down]    Split the active pane (default: right)
+
+INPUT COMMANDS
+  send <text>                       Send text to the active terminal
+  send-key <keystroke>              Send a key (e.g. Enter, ctrl-c, Tab)
+  read-screen                       Read the current terminal screen content
+
+NOTIFICATION COMMANDS
+  notify --title <title> --body <body>   Show a notification in wmux
+
+SYSTEM COMMANDS
+  set-status <text>                 Set a status message on the active workspace
+  set-progress <0-100>              Set a progress value on the active workspace
+  identify                          Show wmux app info
+  capabilities                      List all supported RPC methods
+
+BROWSER COMMANDS
+  browser snapshot                  Return the full page HTML of the active browser surface
+  browser click <selector>          Click an element by CSS selector
+  browser fill <selector> <text>    Fill an input field by CSS selector
+  browser eval <code>               Execute JavaScript in the browser context
+  browser navigate <url>            Navigate the browser surface to a URL
+
+GLOBAL FLAGS
+  --json      Output raw JSON (useful for scripting)
+  --help      Show this help text
+
+EXAMPLES
+  wmux list-workspaces
+  wmux new-workspace --name dev
+  wmux send "echo hello"
+  wmux notify --title "Done" --body "Build finished"
+  wmux identify --json
+  wmux browser snapshot
+  wmux browser navigate "https://example.com"
+  wmux browser click "#login-btn"
 `.trimStart();
 const WORKSPACE_CMDS = new Set([
     'list-workspaces',

package/dist/cli/shared/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENV_KEYS = exports.PIPE_NAME = exports.IPC = void 0;
+exports.ENV_KEYS = exports.IPC = void 0;
 exports.getPipeName = getPipeName;
 exports.getAuthTokenPath = getAuthTokenPath;
 // IPC Channel names
@@ -11,6 +11,8 @@ exports.IPC = {
     PTY_DISPOSE: 'pty:dispose',
     PTY_DATA: 'pty:data',
     PTY_EXIT: 'pty:exit',
+    PTY_LIST: 'pty:list',
+    PTY_RECONNECT: 'pty:reconnect',
     SHELL_LIST: 'shell:list',
     SESSION_SAVE: 'session:save',
     SESSION_LOAD: 'session:load',
@@ -24,6 +26,8 @@ exports.IPC = {
     // Clipboard (main process bridge)
     CLIPBOARD_WRITE: 'clipboard:write',
     CLIPBOARD_READ: 'clipboard:read',
+    CLIPBOARD_READ_IMAGE: 'clipboard:read-image',
+    CLIPBOARD_HAS_IMAGE: 'clipboard:has-image',
     // Phase 4: Auto updater
     UPDATE_CHECK: 'update:check',
     UPDATE_AVAILABLE: 'update:available',
@@ -33,12 +37,21 @@ exports.IPC = {
     UPDATE_INSTALL: 'update:install',
     // Settings sync (renderer → main)
     TOAST_ENABLED: 'settings:toast-enabled',
+    // Agent critical action approval
+    APPROVAL_REQUEST: 'approval:request',
+    // File system
+    FS_READ_DIR: 'fs:read-dir',
+    FS_READ_FILE: 'fs:read-file',
+    FS_WATCH: 'fs:watch',
+    FS_UNWATCH: 'fs:unwatch',
+    FS_CHANGED: 'fs:changed',
 };
-// Named Pipe path for wmux API
+// Named Pipe / Unix socket path for wmux API
 // Fixed name so MCP clients (e.g. Claude Code) can reconnect across wmux restarts
-exports.PIPE_NAME = '\\\\.\\pipe\\wmux';
 function getPipeName() {
-    return exports.PIPE_NAME;
+    if (process.platform === 'win32')
+        return '\\\\.\\pipe\\wmux';
+    return '/tmp/wmux.sock';
 }
 // Environment variable names injected into PTY sessions
 exports.ENV_KEYS = {