wmux Guide: Multi-Agent Workspace Multiplexer Setup

Problem: multi-agent CLI work scatters

Running Claude Code, Codex, and Gemini CLI at once usually scatters:

📑Table of Contents

1. Feature comparison snapshot
2. What wmux is: workspace multiplexing, not a tmux port
3. Core capabilities: panes, fan-out, and coordination
4. Install path: Windows, macOS, and version checks
5. Operational guardrails
6. Adoption checklist: try now or wait
7. Author Perspective
8. FAQ
9. Summary: three steps for today

• windows
• git worktrees (parallel working directories for one repository)
• dangerous-command approvals
• crash recovery

Classic terminal splitters and tmux multiplex terminals well, but they do not own agents, worktrees, a real browser, and agent-to-agent channels as one workspace.

---

What wmux owns

wmux (wmux.app) is a workspace multiplexer: a daemon-managed workbench that keeps terminals, agents, worktrees, and related tools together. The daemon owns:

• terminals
• agents
• git worktrees
• browser
• channels

Where tmux splits a terminal, wmux keeps that workspace side available after quits, crashes, and OS reboots.

---

Distribution defaults

Distribution defaults called out by the project:

• License: MIT
• Telemetry: not stated in the current README
• Account: not required

---

Scope of this guide

This guide covers the product boundary, install path, operational guardrails, and a practical adoption checklist so you can decide what to try today.

---

Feature comparison snapshot

How to read the comparison

The useful difference is not “does it split panes?” but whether a multi-agent workbench stays daemon-owned. Condensing the official comparison axes into two scan-friendly tables:

---

Multiplexing and persistence

Dimension	wmux	tmux	Windows Terminal / iTerm	VS Code terminal	Typical agent manager
Split panes	Yes (independent PTYs)	Yes	Yes	Yes	Varies
Persist after app quit	Daemon-owned restore	Session design dependent	Weak / product-specific	IDE-dependent	Varies
Workspace restore after OS reboot	Workspace, scrollback, channels intended to return	Needs custom design	Generally no	Generally no	Often weak
Worktree fan-out (max 8) + hunk harvest	Yes	DIY	No	No / extensions	Limited
Orchestrator / Fleet View	Yes (e.g. Ctrl+Shift+A)	No	No	No	Varies

---

Coordination, tools, and license

Dimension	wmux	tmux	Windows Terminal / iTerm	VS Code terminal	Typical agent manager
Dangerous-command approval gate	Yes	DIY	No	No	Varies
Channels / agent-to-agent	Yes	No	No	No	Varies
Real Chrome + CDP browser	Yes	No	No	No / extensions	Varies
Zero-config MCP	Yes (86 tools claimed)	No	No	Manual	Often manual
License	MIT	Implementation-specific	Product-specific	Product-specific	Product-specific

Sources: wmux.app, GitHub openwong2kim/wmux, official Releases, and Protocol docs (checked August 17, 2026).

---

Official numeric anchors

• Worktree fan-out: up to 8
• MCP: 86 tools (browser, terminal, panes, channels, A2A, and more)
• Scrollback: up to 999K lines
• Latest release: v3.43.0 (released August 16, 2026; verify on official Releases)
• 8-pane echo latency p50: 4.6ms (vendor measurement note)

---

Package-catalog corroboration

Microsoft-hosted winget-pkgs also carries PackageIdentifier openwong2kim.wmux. Its update timing can lag GitHub Releases, so verify the package version before installation.

That corroborates installability and product class outside the origin README alone.

---

What wmux is: workspace multiplexing, not a tmux port

What layer it owns

wmux’s job is to direct multi-vendor AI coding CLIs on one work surface.

Detected agents listed by the project include:

• Claude Code
• Codex CLI
• Gemini CLI
• Aider
• OpenCode
• GitHub Copilot CLI

---

Boundary versus tmux

Keep the split clean:

• tmux multiplexes terminals
• wmux multiplexes a workspace: terminals plus agent operations, git worktrees, built-in browser, and channels under a daemon

---

What persistence restores

Persistence is easy to over-read.

• Intended to return after quit/crash/reboot: workspace state, scrollback, and channels
• Still ends with the OS: agent processes themselves need reattach or Resume

Think “the bench comes back,” not “every model conversation stays magically alive.”

---

Platform notes

Platform notes that matter in practice:

• Windows: direct ConPTY (no WSL required), Windows 10 1903+ x64
• macOS: forkpty with signed/notarized DMG for Apple Silicon
• Linux: experimental AppImage/.deb/.rpm — do not treat as production baseline

---

Independent class corroboration

Independent catalogs reinforce the class beyond origin docs.

• Korean Wikipedia: describes a Windows-native AI-agent terminal multiplexer on ConPTY/Electron with session restore and winget install openwong2kim.wmux
• SkillsLLM: catalogs the same openwong2kim/wmux project as a multi-agent workspace multiplexer and attaches a third-party npm-audit WARNING snapshot useful as a dependency-hygiene signal

Source

---

Core capabilities: panes, fan-out, and coordination

Side-by-side panes

Run Claude Code, Codex, Gemini, and peers in one window as independent PTYs.

Common fit cases:

• Multi-vendor bake-offs
• Role splits such as “implement in A, review in B” without a pile of OS windows

Fleet View (Ctrl+Shift+A in the official UI) is the overview for role delegation and done-when loops via .claude skills.

---

Worktree fan-out and harvest

Expand one prompt into up to eight isolated worktrees, then adopt diffs hunk-by-hunk with all-or-nothing semantics, one-click PR, and a cleanup list for leftovers. In this article, fan-out means expanding work across worktrees; harvest means collecting the diffs worth adopting.

Evaluation focus:

• If you already compare approaches with manual git worktrees, check whether fan-out → adopt shortens that loop
• That harvest path is the main reason “just use tmux” is incomplete for this product class

---

Channels, A2A, and approval gates

Slack-style channels and agent-to-agent messages support task handoff, with history intended to survive reboot.

Safety boundary:

• Execute approval gates pause destructive patterns such as rm -rf, git push --force, and DROP TABLE before they run
• Important when parallelism multiplies blast radius

---

Browser and MCP

A real Chrome instance over CDP (Chrome DevTools Protocol) is built in, with React-safe input and CJK composition called out by the vendor.

MCP (the connection surface for calling external tools from an agent) and provider boundary per project docs:

• Registers zero-config on first launch
• 86 tools spanning browser, terminal, panes, channels, and A2A
• Workspace-scoped tokens
• wmux itself does not call AI APIs or auto-capture agent output
• Provider billing and ToS remain your responsibility

---

Install path: Windows, macOS, and version checks

Windows (prefer winget)

Start with the package install below. After it completes, run the minimum smoke test in the next subsection before evaluating fan-out or MCP.

winget install openwong2kim.wmux

Alternatives and caveats:

• Alternatives: Chocolatey, Setup.exe, and a PowerShell one-liner
• Setup.exe caveat: may trip SmartScreen because of a SignPath test certificate (“unknown publisher”)
• Managed machines / Smart Application Control: prefer winget, as official FAQ guidance implies

Third-party WinGet UIs such as wingetgui.com also list openwong2kim.wmux with side-by-side agent, browser automation, MCP, and session persistence language—useful packaging corroboration.

---

macOS

Install the signed, notarized DMG from GitHub Releases into Applications, then put the CLI on PATH on first launch. Current distribution targets Apple Silicon; Intel-only Macs need issue-level confirmation rather than assumed support.

---

Linux

Experimental packages exist, but treat them as non-baseline. Evaluate on Windows or Apple Silicon macOS first if you need reproducible ops conclusions.

---

Minimum smoke test after install

Run these checks in order:

1. Launch your primary agent in a single pane
2. Open two panes with different vendors and open Fleet View
3. Restart the app and confirm workspace/scrollback return

If these fail, skip fan-out and MCP deep dives until the bench is stable.

---

Operational guardrails

Treat approval gates as required, not optional

Intentionally trigger one dangerous command and confirm the stop. Disabling gates before fan-out multiplies risk by worktree count.

---

Pin MCP scope

Zero-config lowers install friction; it does not define team policy. Decide which tools are allowed in which workspace before broad rollout.

---

Keep wmux web on the default loopback read-only posture

Keep the default posture unless you explicitly opt into input or exposure. Convenience is not a reason to publish the control surface.

---

Read third-party dependency signals

SkillsLLM’s WARNING from npm-audit is not an official product audit, but it is a reminder to track dependency updates even for MIT desktop tools whose current telemetry posture should be verified.

---

Do not confuse layers

wmux orchestrates local agent CLIs. Auth, spend, and data handling still follow each AI provider.

---

Adoption checklist: try now or wait

Strong reasons to try

• You want physical multi-vendor CLI parallelism (Claude Code / Codex / Gemini and peers)
• You want GUI harvest for worktree experiments (hunk adopt / PR)
• You need a Windows-native bench beyond plain tmux for agent ops
• You want approval gates and channels on the same surface

---

Reasons to wait or skip

• Intel-only Mac or hard Linux production requirement
• One agent plus existing tmux/IDE terminals already enough
• Corporate signing/SmartScreen policy blocks even winget
• Experimental builds cannot become a team baseline

---

Validation checklist for today

1. Confirm OS: Windows 10 1903+ x64 or macOS Apple Silicon
2. Install via winget or DMG; start one agent in a single pane
3. Run two-pane multi-vendor layout and open Fleet View
4. Try a tiny fan-out (two worktrees) and hunk adopt
5. Fire one dangerous command on purpose and confirm the approval gate
6. Restart the app and verify workspace/scrollback/channel restore
7. Review MCP tool list and workspace scope
8. For teams, write down “no public web UI” and provider ToS ownership

If steps 2–5 fail, keep wmux as a comparison experiment rather than a default bench.

---

Author Perspective

When comparing wmux as a multi-agent workbench, three criteria come first:

1. Whether multi-vendor CLIs can run side by side in one window
2. Whether worktree harvest closes with fewer steps than manual git worktrees
3. Whether approval gates and post-restart workspace restore can be reproduced on a real machine, not only in marketing copy

If those three are weak, MCP tool counts and UI polish are thin reasons to standardize on the product.

---

FAQ

Q1. Is wmux a tmux port?

No. It offers tmux-like splitting, but the unit of management is a workspace (agents, worktrees, browser, channels), not terminals alone.

---

Q2. Do I need WSL on Windows?

No. wmux uses ConPTY directly.

---

Q3. Does macOS Intel work?

Current signed DMGs target Apple Silicon. Treat Intel support as unconfirmed unless upstream issues say otherwise.

---

Q4. Can Claude, Codex, and Gemini run together?

Yes—independent PTYs per pane, plus channels/A2A for coordination.

---

Q5. Do conversations survive reboot untouched?

Workspace, scrollback, and channels are intended to restore. Agent processes still need reattach/Resume after OS stop.

---

Q6. Pricing and telemetry?

wmux is MIT-distributed and does not require an account. The current README does not promise no telemetry, so check the repository privacy and security notes before organizational deployment. Provider model usage remains separate.

---

Summary: three steps for today

1. Install with winget (Windows) or the signed DMG (Apple Silicon macOS) and pass a single-agent smoke test
2. Parallelize two vendors once and confirm the approval gate stops a dangerous command
3. Fan out a tiny worktree harvest and decide adopt, hold, or skip

wmux is a multi-agent workbench, not “another terminal splitter.” Validate on your OS and policy first, then expand only what the checklist proves.

Related articles:

• 13580
• 13621
• 13623