Skip to content

README.md

Latest commit

 

History

History
303 lines (228 loc) · 11.2 KB

README.md

File metadata and controls

303 lines (228 loc) · 11.2 KB

wmux — cmux for Windows

Run Claude Code + Codex + Gemini CLI side by side. Windows-native terminal multiplexer with an MCP bridge and browser automation — the fastest way to run multiple AI CLI agents in one window.

Windows 10/11 Electron 41 License: MIT GitHub stars

Still using one terminal for your AI coding agents on Windows?

macOS has cmux — a tmux-based terminal multiplexer for AI agents.

Windows has no tmux. Without WSL, there was no way.

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 in 30 seconds

Winget (recommended):

winget install openwong2kim.wmux

Chocolatey:

choco install wmux

Installer:

Download wmux Setup.exe

One-liner (PowerShell):

irm https://raw.githubusercontent.com/openwong2kim/wmux/main/install.ps1 | iex

Why wmux?

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.

Tmux-style prefix mode — Ctrl+B then a single action key (split, focus, new workspace…) for muscle-memory terminal navigation. 13 actions, fully rebindable.

Floating pane — `Ctrl+`` for a Quake-style dropdown terminal that lives outside your main layout. Stays alive across toggles.

Scroll bookmarks — Ctrl+M marks the current scroll position, Ctrl+Up/Down jumps between marks. Indicators render on the gutter.

Smart right-click — Windows Terminal style. Selection → instant copy. Empty area → instant paste. Link → small Open / Copy Link menu. Zero modal interrupts.

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
Read commands semantically (OSC 133) terminal_read_events
Send command terminal_send
Manage workspaces workspace_list / surface_list / pane_list
Agent-to-agent messaging a2a_send / a2a_broadcast / a2a_whoami
Delegate tasks across agents a2a_task_send / a2a_task_query / a2a_task_cancel
Company mode coordination company_a2a_send / company_a2a_inbox / company_a2a_status

Multi-agent: Every browser tool accepts surfaceId — each Claude Code session controls its own browser independently. A2A tools route messages between sibling agents in the same wmux instance.

5. Session persistence — like tmux

Terminal sessions survive app restarts. Close wmux and reopen — your sessions are still there, scrollback intact.

  • App restart: Daemon keeps PTY processes alive in the background. Reconnects instantly.
  • Reboot: Sessions are recovered with saved scrollback and working directory. wmux auto-starts on login.
  • Auto-update: Checks for updates via GitHub Releases. Toggle on/off in Settings.

6. 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

All Features

Terminal

  • xterm.js + WebGL GPU-accelerated rendering
  • ConPTY native Windows pseudo-terminal
  • Unicode 11 width tables — correct CJK / emoji rendering for cursor-positioning TUIs (Claude Code, vim)
  • Split panes — Ctrl+D horizontal, Ctrl+Shift+D vertical
  • Tabs — multiple surfaces per pane
  • Floating pane — Quake-style dropdown terminal, dedicated PTY, `Ctrl+``
  • Smart right-click — selection → instant copy, empty area → instant paste, link → Open / Copy Link menu
  • Scroll bookmarks — Ctrl+M mark, Ctrl+Up/Down jump, gutter indicators
  • Vi copy mode — Ctrl+Shift+X
  • Search with regex toggle — Ctrl+F
  • 999K line scrollback with disk persistence
  • Shell integration (OSC 133) — semantic prompt / command boundaries for terminal_read_events. Auto-injected for pwsh / bash. Constrained Language Mode safe (v2.7.1).

Keybindings

  • Tmux-style prefix mode — Ctrl+B then action key, 13 default actions (splits, focus, workspaces, palette, floating pane, …)
  • Customizable bindings + custom keymaps in Settings
  • Reset-to-defaults available

Workspaces

  • Sidebar with drag-and-drop reordering
  • Ctrl+1~9 quick switch
  • Multiview — Ctrl+click to view multiple workspaces side by side
  • Layout templates — save current pane layout, restore via Command Palette ("recent" category)
  • Full session persistence — layout, tabs, cwd, scrollback all restored
  • One-click reset in Settings

Browser + CDP Automation

  • Built-in browser panel — Ctrl+Shift+L
  • Navigation bar, DevTools, back/forward
  • Element Inspector — hover to highlight, click to copy LLM-friendly context
  • Full CDP automation: click, fill, type, screenshot, JS eval, key press

Notifications

  • 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
  • Windows startup registration (survives reboot)
  • Dead session TTL reaping (24h default)

Auto-Update

  • Automatic update checks via GitHub Releases
  • Toggle on/off in Settings > General
  • Manual check available in Settings

Themes

Catppuccin Mocha, Monochrome, Sandstone

i18n

English, Korean, Japanese, Chinese

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 to multiview
Ctrl+Shift+G Exit multiview
Ctrl+Shift+L Open browser
Ctrl+B then <key> Tmux-style prefix mode (13 actions)
Ctrl+Shift+B Toggle sidebar
`Ctrl+`` Toggle floating pane (Quake-style)
Ctrl+K Command palette
Ctrl+I Notifications
Ctrl+, Settings
Ctrl+F Search terminal (with regex toggle)
Ctrl+M Add scrollback bookmark
Ctrl+Up / Ctrl+Down Jump prev / next bookmark
Ctrl+Shift+X Vi copy mode
Right-click Smart copy (selection) / paste (empty) / link menu
F12 Browser DevTools

Development

git clone https://github.com/openwong2kim/wmux.git
cd wmux
npm install
npm start           # Dev mode
npm run make        # Build installer

Requirements (dev 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 / ConPTY)
├── PTYBridge (data forwarding + ActivityMonitor)
├── AgentDetector (gate-based agent status)
├── SessionManager (atomic save with .bak recovery)
├── ScrollbackPersistence (terminal buffer dump/load)
├── PipeServer (Named Pipe JSON-RPC + token auth)
├── McpRegistrar (auto-registers MCP in ~/.claude.json)
├── WebviewCdpManager (CDP proxy to <webview>)
├── DaemonClient (daemon mode connector)
├── AutoUpdater (GitHub Releases feed)
└── ToastManager (OS notifications + taskbar flash)

Renderer Process (React 19 + Zustand)
├── PaneContainer (recursive split layout)
├── Terminal (xterm.js + WebGL + scrollback restore)
├── BrowserPanel (webview + Inspector + CDP)
├── NotificationPanel
├── SettingsPanel (auto-update toggle, workspace reset)
└── Multiview grid

Daemon Process (standalone)
├── DaemonSessionManager (ConPTY lifecycle)
├── RingBuffer (circular scrollback buffer)
├── StateWriter (session suspend/resume)
├── ProcessMonitor (external process watchdog)
├── Watchdog (memory pressure escalation)
└── DaemonPipeServer (Named Pipe RPC + token auth)

MCP Server (stdio)
├── PlaywrightEngine (CDP connection, fast-fail)
├── CDP RPC fallback (screenshot, evaluate, type, click)
└── Claude Code <-> wmux Named Pipe RPC bridge

Acknowledgments

  • cmux — The macOS AI agent terminal that inspired wmux
  • xterm.js — Terminal rendering
  • node-pty — Pseudo-terminal
  • Electron — Desktop framework
  • Playwright — Browser automation engine

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