# wmux fans one prompt across worktrees and asks you from a phone

> openwong2kim/wmux is a workspace multiplexer for CLI coding agents: a daemon owns every PTY so panes survive a quit or a reboot, one prompt fans out into up to eight git worktrees, ticked hunks are adopted as a single all-or-nothing git apply, and a blocked agent question reaches your iPhone lock screen.

**openwong2kim/wmux** — Run Claude Code, Codex & Gemini in parallel on Windows & macOS — git worktree fan-out with atomic hunk adoption, approval gates, reboot-surviving sessions

- Repository: https://github.com/openwong2kim/wmux
- Website: https://www.wmux.app
- Stars: 408 · Forks: 69
- Language: TypeScript
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/openwong2kim-wmux

## tmux splits a terminal, wmux splits a workspace

The README defines the category in one comparison. tmux splits a terminal. wmux multiplexes whole workspaces: terminals, agents, git worktrees, a browser, and the channels those agents coordinate over. Everything in that list is owned by a daemon that keeps it running across quits, crashes and full reboots.

That daemon is the load-bearing part. A standalone daemon owns every PTY, so closing the application leaves your sessions running with their processes intact. After a crash or a reboot, a recovered pane offers a Resume action, and clicking it types the agent command back in. For Claude Code there is a second click that appends the exact session's `--resume <id>`, provided wmux knew which session the pane was holding, otherwise it falls back to the most recent one.

There is also a declarative layer. Panes declared in `wmux.json` are supervised and restarted automatically, so a workspace that is important enough to write down does not need to be rebuilt by hand after a crash. The version moves fast: v3.65.0, v3.64.0 and v3.63.0 were published on 1, 30 and 29 September 2026.

## Windows and macOS are first class, Linux is experimental

Installation is per platform and the differences are stated rather than smoothed over. On Windows a package manager skips the SmartScreen prompt:

```powershell
winget install openwong2kim.wmux    # or: choco install wmux
```

Downloading Setup.exe directly does not, because the installer is signed with a SignPath test certificate for now, so SmartScreen shows an unknown publisher and the README links to an explanation. On Apple Silicon macOS you download the .dmg and drag wmux to Applications; that build is Developer ID signed and notarized, and on first launch the `wmux` CLI installs itself onto your PATH. Linux has experimental AppImage, .deb and .rpm builds on the releases page.

Updates are automatic on the two native platforms. Windows x64 and macOS arm64 check for a release every 30 minutes and verify it against a published SHA-256 before installing, so an update is not taken on trust alone.

The iPhone side is a free App Store app that pairs with the daemon on your Mac: start `wmux web` over HTTPS and scan the QR code it shows. The sidebar Remote button has a one-click Tailscale option, which is how the phone reaches a machine that is not on the same network.

## One prompt becomes up to eight worktrees

The fan-out is the feature the product name implies. One prompt is spread into up to 8 tasks, and each task gets its own git worktree on a fresh `wtask/*` branch, its own agent pane and a private mission channel. Eight attempts at the same change can therefore run at once without fighting over a working tree.

The review step is where the design is unusual. You review the diffs side by side, tick the hunks you want across files, and adopt them as one all-or-nothing `git apply`. Your tree takes the whole selection or stays untouched. That is a deliberate trade: there is no partial application, so a selection that mixes a good change with a broken one is rejected as a unit rather than half applied and debugged.

After adoption the task closes, or you open a pull request in one click. Since the branches are already separate, the pull request step is not a merge conflict exercise but a description of work that was reviewed as a set before it landed.

## Two browser backends, and a third that only opens tabs

Agents drive the browser through wmux's own MCP tools, and the toolset is the same whichever backend you pick: navigate, click, type, snapshot, screenshot, stateful `browser_repl` sessions, and `browser_replay` for recorded flows. You watch every page they touch. The choice is made in Settings under Browser.

The built-in option is an embedded browser pane that opens as a split in the agent's workspace. Each agent gets its own, and the rule is stated explicitly: no agent drives another agent's pane. That isolation matters when eight fan-out tasks are browsing at once.

The other backend is a real Chrome over CDP, chosen as the dedicated agent browser. Agents drive it in their own tabs, and it keeps its own persistent profile, so signing in once leaves the logins in place, separate from your daily browser. Each workspace can bind its own Chrome profile.

There is a third mode called External, and it is deliberately limited: it only opens and navigates tabs in your default browser. That is the option to pick when you want to see the pages in your own session and do not want an agent automating a profile that holds your accounts.

## Agents message each other with send_message

Because panes hold different CLI agents, the messaging has to work across them. Agents in different panes message each other through wmux whichever CLI they run, and the README walks through one exchange: Claude Code changes a function and asks the Codex pane next to it for a review using `send_message`, Codex reads the file and sends its review back the same way, and Claude adds the test Codex suggested.

A busy agent is not made to wait. It gets a one-line notice naming the sender and reads the full message later with `a2a_task_query`. That is the difference between a channel that blocks and one that queues.

Coordination beyond two agents is covered by an orchestrator that hands a task to an idle pane and relays the answer back, and channels described as durable rooms agents read, post and get @-mentioned into, with each message carrying a server-verified sender. Alongside that sits an execute approval gate, which stops any agent from running code in your workspace without your OK. The Fleet View, `Cmd+Shift+A` or `Ctrl+Shift+A` on Windows and Linux, gathers every agent across every workspace in one panel with blocked ones first and one inbox per pending approval.

## The push relay gets a sealed envelope, the Live Activity does not

The phone feature has an explicit privacy contract, and it is worth reading rather than assuming. When an agent stops to ask something, whether a Claude Code `AskUserQuestion` prompt or a tool call held by an approval gate, the question lands on the iPhone lock screen as a push notification. You pick an option, Approve or Deny in the Inbox, and the pane on your desktop advances.

Terminals and agent output travel straight from your Mac to your phone, against the daemon you run. Notification content reaches the push relay only as a sealed envelope that the relay cannot read, which is the claim that makes answering from a lock screen acceptable at all.

There is one stated exception. The lock screen Live Activity carries six plain counts: pending approvals, running, working and idle agents, blocked panes and longest wait. When it starts it also carries your Mac's hostname. No pane names and no question text appear in it, and the full detail lives in `docs/phone-client-contract.md`. `wmux web` on its own is read-only and loopback-only by default, so exposing it is a deliberate step rather than the default state.

## 78 MCP tools in three profiles, plus four CLI verbs

The tool surface is large and self-registering: 78 MCP tools covering browser, terminal, panes, channels, agent to agent messaging, fan-out and orchestrator functions, registering themselves in three load-out profiles named `full`, `core` and `commander`. The same capabilities are scriptable through the CLI, with four named commands in the README: `send`, `read-screen`, `list-panes` and `channel post`.

Two scheduling features sit on top. Prompt schedules queue an exact prompt for one agent session at +1h, +5h or +24h, one-shot or repeating, and the queued prompt waits for the session to be idle before it is delivered rather than interrupting work in progress. One-click loops put the orchestrator on an objective with per-iteration steps and a done-when checklist, and keep working across restarts.

Notifications round it off: desktop toasts when an agent finishes, and flags on commands such as `rm -rf`, `git push --force` and `DROP TABLE`, which is a short list covering the destructive operations an agent is most prone to get wrong.

## Five tsconfigs and a postinstall that patches native modules

The repository is an Electron application with several separately built pieces, and the build matrix is visible in the scripts. There are five tsconfig files, for the CLI, the daemon, the harness, the MCP surface and the rig, plus four Vite configs for main, preload, renderer and web, and four Vitest configs for the base suite, the harness, the rig and the runtime tests.

Each target compiles then bundles: the daemon goes through `tsc` and esbuild with `node-pty` and `koffi` marked external, which is how the native PTY and FFI pieces stay native instead of being packed. The CLI has its own compile and bundle followed by a bridge copy step, and the MCP entry is built separately because it runs as its own process. `electron-forge` handles start, package and make, and the package is marked private with the CLI exposed as a bin.

The install step is not trivial either. Postinstall runs `scripts/fix-node-pty.js` and then `scripts/apply-patches.mjs`, so a fresh checkout repairs the native PTY build and applies patches from the `patches/` directory before anything runs. Licensing has its own tooling: a license allowlist, a check script, a notices generator, and a `THIRD_PARTY_NOTICES` file. Packaging spans several ecosystems at once, with a Chocolatey directory, an `.claude-plugin/` directory, changelog fragments in `changelog.d/`, and working documents kept in the tree as `decisions.md`, `progress.md`, `handoff.md`, `DESIGN.md` and `ARCHITECTURE.md`.

## Conclusion

Fit for someone running two or more CLI agents on the same repository who wants parallel attempts on separate branches, a single review surface across their diffs, and an approval decision that does not require being at the keyboard. Not fit as a single agent workspace, since the fan-out, the channels and the fleet panel all assume more than one pane, and not for Linux as anything but a trial, where the AppImage, .deb and .rpm builds are described as experimental. Before trusting it with a repository, read how hunk adoption works, because it is all or nothing by design, and check the privacy contract in the phone client docs, since the lock screen activity is the one place identifiers are exposed by choice.

## FAQ

### What is wmux and how does it differ from tmux?

tmux splits a terminal. wmux multiplexes whole workspaces: terminals, agents, git worktrees, a browser, and the channels those agents coordinate over, all owned by a standalone daemon that keeps them running across quits, crashes and full reboots. It ships as an Electron application with a CLI binary also named wmux, currently at version 3.65.0.

### How do I install wmux on Windows and macOS?

On Windows use winget install openwong2kim.wmux or choco install wmux, because a package manager skips the SmartScreen prompt while a direct Setup.exe download is signed with a SignPath test certificate and shows an unknown publisher. On Apple Silicon macOS, download the .dmg and drag it to Applications; it is Developer ID signed and notarized and the wmux CLI installs itself onto your PATH on first launch. Linux AppImage, .deb and .rpm builds are experimental.

### Can I answer an AI agent from my phone with wmux?

Yes. Start wmux web over HTTPS and scan the QR code it shows, or use the one-click Tailscale option in the sidebar Remote button. A Claude Code AskUserQuestion prompt or a tool call held by an approval gate arrives as a lock screen push notification, and your answer advances the pane on your desktop. Notification content reaches the push relay as a sealed envelope it cannot read.

## Sources

- [License: MIT](https://github.com/openwong2kim/wmux/blob/main/LICENSE)
- [openwong2kim/wmux on GitHub](https://github.com/openwong2kim/wmux)
- [Project website](https://www.wmux.app)
- [README](https://github.com/openwong2kim/wmux/blob/main/README.md)
- [Releases](https://github.com/openwong2kim/wmux/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openwong2kim-wmux