Introduction

Getting started

vmux is a terminal multiplexer for Linux (and macOS), built for working alongside AI coding agents. Panes run inside a small daemon, so when SSH drops or you close the terminal, your agents keep working.

Install

Prebuilt binary — Linux (x86_64, aarch64) and macOS (Apple silicon, Intel):

curl -fsSL https://raw.githubusercontent.com/UAEpro/vmux/main/install.sh | sh

This picks the build for your platform, puts vmux in ~/.local/bin (override with VMUX_INSTALL_DIR) and verifies the release checksum. The Linux binaries are static, so they run on any distro.

Or from crates.io, with Rust 1.87 or newer:

cargo install vmux-tui

The crate is vmux-tui because vmux was already taken on crates.io. The command it installs is still vmux.

Windows is not supported. vmux depends on Unix domain sockets, fork / setsid, and POSIX signals — there is no native Windows build. WSL is fine, since it is Linux: the Linux binary and source builds work there the same as on bare metal.

vmux shells out to a few tools. git and curl are worth having. ss and tailscale are optional, and unlock port detection and the phone relay respectively. vmux makes no network calls of its own beyond a once-a-day update check (disable with VMUX_NO_UPDATE_CHECK=1).

Attach

That is the whole thing — attach starts a daemon if one is not already running:

vmux attach

From there, or from any other shell:

# a workspace with an agent in it
vmux workspace new --name agents --command "claude"

# split the current pane and run tests beside it
vmux split right --command "cargo test" --title tests

# let agents report status into the sidebar
vmux hooks install

# from inside a pane: where am I?
vmux identify --json

After an SSH drop, or tomorrow morning:

vmux sessions               # what is still running
vmux --session work attach  # pick up where you left off

A workspace is the unit you think in — it has a directory, so a new pane opens where you expect, and the sidebar shows its git branch, its listening ports, and its agent's status: busy, needs input, done, or failed. Read the full model in Concepts.

Next steps

Learn the keyboard shortcuts — one prefix key drives everything.
Wire up agent hooks so Claude Code, Codex, and Grok report status automatically.
Pair your phone with the phone relay to check on agents away from your desk.
Skim the CLI reference — every command attach can do, a script can do too.

Edit this page on GitHub

Getting started

Install

Attach

See it in the sidebar

Next steps