wmux Documentation

Everything you need to know to get started with wmux, even if you've never used a terminal multiplexer in your life. This guide takes you from zero to confident, step by step.

What is wmux?

wmux is a Windows desktop application that lets you keep several terminals open at the same time, organized in vertical tabs, with the ability to split any tab into multiple panes. Think of it as the Windows equivalent of tools like tmux (Linux/macOS), Ghostty, or Warp — but built specifically for working with AI agents like Claude Code.

Concretely, when you launch wmux you get:

• A single window that can hold as many terminals as you want
• A sidebar listing all your workspaces, with live git branch, working directory, active ports, GitHub PR status, and unread notifications
• A built-in web browser (on the right) that can show what your Claude Code agent is doing in real time
• Visual and audio notifications when an agent finishes a task or needs your input
• Automatic Claude Code integration, with nothing to configure

Who is this for? Anyone who wants to run several AI agents in parallel on Windows and keep track of what they're doing. If you already use Claude Code and you're tired of juggling multiple terminal windows, wmux is for you.

Installation

wmux ships as a portable zip archive. There is no installer: you download, extract, and run. Here are the exact steps:

1. Download the latest release

Head to the GitHub releases page and grab the file named wmux-X.Y.Z-win-x64.zip (where X.Y.Z is the most recent version). The zip is about 150 MB.

2. Extract the zip

Right-click the downloaded file, choose Extract All, and pick a destination folder. I recommend C:\Users\YourName\wmux for easy access. Avoid Program Files unless you are running as administrator.

Get-ChildItem -Recurse | Unblock-File

3. Launch wmux

In the folder where you extracted wmux, double-click wmux.exe. The first time, Windows SmartScreen will show a blue screen with "Windows protected your PC". That's normal — wmux is not yet signed with an expensive Authenticode certificate. Click More info, then Run anyway.

wmux opens with a dark window and a default PowerShell terminal. Welcome.

First launch

When you open wmux for the first time, here is what you see:

• On the left: the sidebar with a single workspace named something like ws-1. That's your current "tab".
• In the center: a PowerShell terminal ready to accept commands.
• On the right: possibly an empty browser pane (you can close it with Ctrl+Shift+B if you don't need it).
• At the top: a title bar with the wmux name, a notification bell, and the standard window controls.

Double-click the workspace in the sidebar to rename it. I recommend naming your workspaces by project — for example my-site, api-backend, etc.

Core concepts

wmux organizes your work into four layers. Understanding these four words will save you a lot of time.

Workspace

A workspace is a big container. Think of it as a complete "session" for a project: a workspace can hold several panes, and each pane several tabs. You switch between workspaces via the sidebar or with Ctrl+1, Ctrl+2, etc.

Pane

A pane is a visual block inside the workspace. When you split your screen in two to have a terminal on the left and another on the right, you create two panes. Each pane can show a terminal, a browser, or a markdown document.

Surface (tab)

A surface is a tab inside a pane. In a single pane, you can keep several tabs open at once (for example 3 different terminals) and switch between them with Ctrl+Tab. Think of browser tabs, but for your terminals.

Sidebar

The sidebar on the left lists all your workspaces. For each one it displays in real time: the git branch, whether the directory has uncommitted changes, the working directory, the open ports (useful for dev servers), the number of running agents, the GitHub pull request status, and the unread notifications.

Keyboard shortcuts

wmux has 50+ shortcuts, but you really only need about a dozen day-to-day. Learn these and you'll be productive:

You can customize any shortcut in Settings → Keyboard shortcuts. If you're coming from tmux or Ghostty, presets are available to mirror your existing muscle memory.

Working with Claude Code

This is where wmux really earns its keep. wmux automatically detects Claude Code and wires up its integration without asking you to configure anything. When you run claude in a wmux terminal, the following happens behind the scenes:

• wmux injects its instructions into ~/.claude/CLAUDE.md (read-only, surgical, non-intrusive) so Claude Code knows it's running inside wmux and uses the embedded browser instead of spawning Playwright.
• Claude Code hooks (SessionStart, PostToolUse, SubagentStop, Stop) are auto-registered. They report in real time to the sidebar what tools the agent is using, how many, whether it's paused, whether it's waiting for your input.
• A CDP proxy on localhost:9222 exposes the embedded browser to Claude Code via chrome-devtools-mcp. Every page, click, and form submission the agent visits shows up in your browser pane.

Concrete result: you run claude, ask it "browse github.com and find the wmux repo", and you watch in real time what it's doing inside the browser pane. No Playwright, no invisible windows, no configuration.

The wmux-orchestrator plugin

To go further with Claude Code, wmux ships with a plugin called wmux-orchestrator. It lets you run several Claude Code agents in parallel on a single task, each in its own visible pane. The plugin analyzes your codebase, splits the task into subtasks, and coordinates everything.

It's explained in full on plugin.wmux.org with an interactive simulator.

Split panes

Having several terminals side by side is often what saves you the most time. wmux makes it trivial.

Split horizontally

Press Ctrl+D. The current pane splits in two: the original on the left, a new empty terminal on the right. Focus automatically moves to the new pane.

Split vertically

Press Ctrl+Shift+D. The pane splits horizontally: the original on top, the new one on the bottom.

Resize

Grab the separator bar between two panes with your mouse and drag. Resizing is smooth. If you need an exact ratio, head to the settings.

Close a pane

Ctrl+Shift+W closes the current pane. If the pane contains several tabs (surfaces), they all close. The neighboring pane automatically takes the freed space.

The embedded browser

wmux ships with a real Chromium browser (not a basic webview) that you can open next to any terminal. It serves two purposes:

1. Watch Claude Code work in real time when it browses the web via chrome-devtools-mcp. Every agent action is visible live, as if you were looking over its shoulder.
2. Read library docs, check a dashboard, open Stack Overflow without leaving wmux.

To open a browser, use Ctrl+Shift+B. A browser pane opens on the right. Type a URL in the address bar, or click the "new surface" button to stack several browser tabs in the same pane.

The browser supports full DevTools (right-click → Inspect), Chrome keyboard shortcuts, and back/forward with Alt+← and Alt+→.

Notifications

When an agent finishes a task or needs your attention, wmux alerts you several ways at once:

• The pane flashes blue (a blue light ring around the affected terminal). That's the primary visual signal inside the active window.
• The sidebar shows a badge next to the affected workspace, with the count of unread notifications.
• The wmux icon in the Windows taskbar flashes. That's the signal when you're on another application.
• A Windows toast notification appears at the bottom right with the workspace title and the message.
• A sound can play (disabled by default, enable in settings).

Notifications are triggered automatically by the shell integration scripts that detect when a command finishes or is interrupted. To trigger one manually from a script, use wmux notify "My message".

Activity indicators

In the sidebar, each surface displays a small colored dot:

• Pulsing orange: a command is running (active agent, build in progress, etc.)
• Green: the last command completed successfully
• Red: the last command failed or was interrupted
• Gray: idle prompt, shell waiting

Save & restore sessions

wmux automatically saves your window state every 30 seconds: workspaces, panes, tabs, working directories, browser URLs. When you close wmux and reopen it, you land back on the exact same layout.

You can also save a named session manually to come back to it later:

wmux session save "before-refactor"
wmux session list
wmux session load "before-refactor"

Sessions are stored in %APPDATA%\wmux\sessions\ as JSON files.

Themes

wmux bundles 450+ ready-to-use themes imported from the Ghostty project, plus the ability to import your own themes from Windows Terminal.

Change theme

Open settings with Ctrl+,, go to Appearance, then Theme. Hover a theme name to preview it. The change applies instantly to every open terminal.

Import a Windows Terminal theme

If you've already set up Windows Terminal with a theme you like, wmux can read it directly:

wmux config import-wt

This imports every colorSchemes entry from your Windows Terminal settings.json and makes it available in wmux.

Import a Ghostty theme

Same idea with a Ghostty config file:

wmux config import-ghostty ~/.config/ghostty/config

Shell integration

For wmux to know what's happening in each terminal (current git branch, directory, last command exit code, active ports), it injects integration scripts into your shell at startup. Three shells are supported:

• PowerShell (Windows PowerShell + PowerShell 7+) — full integration including GitHub PR polling every 45 seconds
• Bash (Git Bash, WSL) — git branch, dirty state, directory, ports
• cmd.exe — basic OSC 9 escape sequences for notifications

Integration is automatic: you don't have to do anything. wmux detects your default shell, injects the script when the terminal launches, and it just works.

If you want to see what is injected, look inside %APPDATA%\wmux\shell-integration\. The scripts are documented and you can tweak them if you want to customize what shows up in the sidebar.

The wmux CLI

wmux is scriptable. When you launch the application, it starts a named pipe (\\.\pipe\wmux) that accepts JSON-RPC v2 commands. The wmux.exe executable is also a client of that pipe: you can use it from any shell to drive wmux from a command line.

A few useful examples

# Create a new named workspace
wmux new-workspace --title "my-project" --cwd C:\Users\me\dev\project

# Split the current pane and run a command inside it
wmux split --down
wmux send "npm run dev"

# List all workspaces
wmux list-workspaces

# Open a URL in the built-in browser
wmux browser open https://github.com/amirlehmam/wmux

# Trigger a notification
wmux notify "Build finished successfully"

# Get the full window tree (JSON)
wmux tree

The full command list is available via wmux --help in any terminal. The CLI is what lets Claude Code and every other automation tool talk to wmux.

The wmux-orchestrator plugin

wmux ships a Claude Code plugin called wmux-orchestrator that turns a single complex task into several agents working in parallel, each in its own visible pane.

For example, if you ask "refactor authentication to use JWT", the orchestrator will:

1. Analyze the codebase and identify all affected files
2. Split the task into subtasks (shared types, service, middleware, tests)
3. Organize the subtasks into waves based on their dependencies
4. Spawn a Claude Code agent per subtask, each in its own wmux pane
5. Coordinate wave transitions automatically
6. Launch a reviewer agent at the end to check consistency

The plugin is already installed with wmux (it's copied into ~/.claude/plugins/cache/ on first launch). You can use it directly with:

/wmux-orchestrator:orchestrate "refactor auth to JWT"

For a full explanation with an interactive simulator, live demo, detailed architecture, and step-by-step usage guide, visit plugin.wmux.org.

Visit plugin.wmux.org

Common issues

wmux won't start, I get an error about node-pty

This is almost always the Mark of the Web blocking native module loading. In PowerShell, navigate to the wmux folder and run Get-ChildItem -Recurse | Unblock-File, then relaunch. If that doesn't fix it, re-download the zip and uncheck Unblock in Properties BEFORE extracting.

Keyboard shortcuts don't work

Check that your antivirus or something like AutoHotkey isn't intercepting combinations. Windows Defender and most consumer antiviruses don't interfere, but some productivity tools do. Test in Settings → Keyboard shortcuts with the "test" button.

Claude Code doesn't recognize wmux

When you run claude in a wmux terminal, verify that the environment variables are injected: run echo $env:WMUX (PowerShell) or echo $WMUX (bash). You should see 1. If you see nothing, the shell integration didn't load — restart the shell or relaunch wmux.

Also check that ~/.claude/CLAUDE.md contains a section starting with # wmux. If it's missing, auto-injection failed. Relaunch wmux from an admin terminal and inspect the logs.

The built-in browser is slow or black

Turn on GPU acceleration in Settings → Advanced → Hardware acceleration. On older machines without a dedicated GPU, it can make a big difference. On very old GPUs or inside a VM, turn acceleration off instead — it can produce visual artifacts.

How do I update wmux?

wmux has a built-in auto-updater that checks for new versions on launch. When an update is available, you see a small notification. Click it and wmux updates itself. You can also force a check via Help → Check for updates, or manually download the latest release from GitHub and replace your installation.

Can I use wmux on macOS or Linux?

No. wmux is built specifically for Windows (it uses ConPTY, native Win32 APIs, and Windows-specific Electron optimizations). On macOS, use cmux, the parent project written in Swift/AppKit. On Linux there's tmux, Ghostty, or Warp — but you won't get the wmux-orchestrator plugin.

Resources

To go further, here's where to look:

• GitHub — github.com/amirlehmam/wmux: source code, releases, issues
• Releases — All versions with changelog
• Discussions — GitHub Discussions to ask questions
• Issues — Report a bug
• Orchestrator plugin — plugin.wmux.org: full plugin documentation with an interactive simulator
• cmux (macOS) — cmux.com: the macOS version wmux is the Windows fork of

Back to wmux.org Download wmux