Introduction

Concepts

The whole model in one tree, plus how vmux keeps a client's screen in sync without ever polling expensively.

Hierarchy

Session  (default, work, …)     one daemon, one socket, one state file
 └── Workspace                  sidebar row: cwd, git branch, ports, agent status
      └── Tab                   strip above the pane grid
           └── Pane             one PTY process

A session is one running daemon with one socket and one state file — most people only ever use default, but a second session (vmux --session dev attach) is a fully separate workspace tree, useful for keeping a debug build away from real work.

A workspace is the unit you think in: a project. It has a directory, so a new pane opens where you expect, and the sidebar shows its git branch, its listening ports (see Ports & forwarding), and its agent's status.

A tab is the strip above the pane grid inside a workspace — a place to group panes for one thread of work (main, tests). Tabs holding a coding agent name themselves automatically; see automatic tab names.

A pane is one PTY process — a shell, an agent, a test runner, anything with a terminal.

Agents report their own state

Panes running a coding agent surface a status in the sidebar, so you can tell at a glance which of six running agents is actually waiting on you:

Status comes from agent hooks, terminal OSC titles, or a manual vmux set-status / vmux notify call — see the guide for how each source is weighted.

Persistence and detach

Panes live inside a small background daemon, not inside your terminal. Closing SSH, shutting the laptop, or losing the connection does not stop anything running in a pane — reattach later and it is where you left it:

vmux sessions               # what is still running, and what is saved on disk
vmux --session work attach  # reattach

Session state — including scrollback — is written to ~/.local/state/vmux/<session>.json under the XDG state directory. A corrupt file is moved aside rather than deleted, so a bad write never silently erases a session.

How the UI stays live without polling hard

The daemon keeps a generation counter that increases on every meaningful change. The attach client polls for a snapshot since the generation it last saw; if nothing moved, the daemon replies { unchanged: true } and the UI skips a repaint. That is why attach feels instant even though it is just a client speaking a request/response protocol — the same protocol every CLI command uses, which is also why scripts and agents can drive a workspace with no special access.

Full architectural detail, including lock ordering and the source map, lives in Architecture.

The daemon is authoritative

Attach is a dumb client: it renders a snapshot and sends RPCs. It keeps no layout or pane state of its own. If you script vmux from an agent or a shell, you are using the exact same interface the attach UI uses — nothing is held back for a "privileged" client.