Install

• Python 3.12 or newer. Check with python --version.
• An installer. uv is the recommended one, pipx works the same way, and pip works with a caveat covered below.
• At least one agent CLI, already installed and logged in. swe-mux does not install, manage, authenticate, or proxy them. If you have none yet, install Claude Code, Codex CLI, or opencode first and log into it there.
• Node is not required. Node 22.6 or newer is needed only if you are building swe-mux from a checkout.

Every method below writes the same three commands: mux (the CLI), muxd (the daemon), and swe-mux (the desktop window and tray). Run exactly one.

# Recommended. Isolated environment, all three commands on PATH globally.
uv tool install swe-mux

# On Windows, take the desktop extra: it is what adds the window and the tray icon.
uv tool install "swe-mux[desktop]"

# The same isolated, on-PATH install, without uv.
pipx install swe-mux

# NOT the same act. Installs into whichever environment is currently active and
# puts nothing on PATH globally, so `mux` works only inside that environment.
pip install swe-mux

• No shortcut, no Start Menu entryWheels have no post-install hook and pip runs no install-time code, so this is structural rather than a step somebody forgot. swe-mux starts from a terminal. On Windows you can create the shortcuts afterwards with mux install-shortcut, which is idempotent and has a --remove.
• No agent CLI is installed or logged inThat stays your own arrangement with each vendor. swe-mux finds the CLIs already on your machine and runs them under your own subscription.

Without [desktop] you still get a swe-mux command, and it fails on a missing import rather than opening a window. The extra wants the WebView2 Runtime, which recent Windows builds already have.

It is Windows-only by declaration: pystray and pywebview both carry a win32 platform marker, so on Linux and macOS the extra resolves to nothing and the daemon plus a browser is the whole product.

muxd                          # the daemon
# then open http://127.0.0.1:8765

swe-mux                       # Windows, with the desktop extra: the same thing in a window

It worked when mux doctor exits 0. It is read-only and reports on the daemon, the supervisor, the frontend build, the agent CLIs it can detect, the tailnet listener, and the background loops. It is the command that tells installed from working.

This is the ordinary outcome of pip install, and its WARNING: The scripts ... are installed in '...' which is not on PATH scrolls past unread.

# The daemon, needing no PATH setup at all: `python -m swe_mux` is exactly `muxd`.
python -m swe_mux

# Where the three executables went (a `Scripts` directory on Windows).
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

# Every file this install wrote, those three included.
pip show -f swe-mux

The honest boundary across all three: no CI job on any host starts a daemon from the published wheel. Installing and running the CLI is proven everywhere. That is not the same claim as working end to end.

uv tool upgrade swe-mux       # or: pipx upgrade swe-mux

# Run from a checkout instead - what you want if you are changing swe-mux itself.
git clone https://github.com/jatoran/swe-mux
cd swe-mux
uv sync --extra desktop
npm --prefix frontend ci        # only the source flow needs Node
npm --prefix frontend run build # a fresh clone serves no UI until this runs once
uv run --extra desktop swe-mux

The frontend bundle is git-ignored build output, so a fresh clone serves a blank page rather than an error until that build has run once. Troubleshooting covers the symptom.

Local text-to-speech and local dictation are --extra voice-local, roughly 400 MB of wheels and model machinery. The Windows desktop bundle always carries it. Without it swe-mux speaks through the operating system's voice engine and dictates through the browser, which is a working configuration rather than a degraded one.