vmux attach

Attach a terminal to a daemon-managed session, detach, reattach, and mirror across clients.

Synopsis

vmux [global-flags] attach [-s NAME | --session NAME]
vmux [global-flags] [--name NAME]                       # bare invocation = attach
vmux [global-flags] new-session [-s NAME]

attach is the verb you use most. It is also the default verb — vmux with no subcommand is the same as vmux attach.

new-session is an alias for attach with the same arguments. There is no separate "create session, do not attach" command for the interactive client; attach creates the session lazily if it does not already exist. To create a session without attaching, use vmux session create.

Global flags

These flags apply to every vmux invocation, not just attach:

Flag	Default	Effect
`--config PATH`	search list	Load a specific config file.
`--socket PATH`	resolved from config	Override the daemon socket path.
`--daemon PATH`	sibling of `vmux`, then `vmuxd` on `PATH`, then `$VMUX_DAEMON_PATH`	Path to a `vmuxd` to auto-launch when no daemon is running.
`-s, --session NAME`	`default`	Session to attach to. The string is also accepted as a UUID for commands that need a session ID.
`--name NAME`	—	Synonym for `--session`.

What attach does

When you run vmux attach, the client:

Resolves the socket path from flags, VMUX_CONFIG, then the default search list.
Connects to the Unix socket. If connect(2) returns ENOENT or ECONNREFUSED and client.autoStartDaemon is true (the default), it spawns vmuxd --daemonize --socket <path> and retries up to 30 times at 100 ms intervals.
Puts the local terminal into raw mode (cfmakeraw) and saves the prior termios.
Emits the xterm "enable mouse + SGR" sequence so mouse events round-trip through the daemon to the active pane.
Sends an attach { sessionName } message. The daemon creates the session named by --session if it does not exist (default default).
Sends a resize { cols, rows } message based on TIOCGWINSZ of stdout.
Enters the I/O loop:
- Polls stdin for keystrokes and forwards them as input { data: [u8] } frames.
- Polls the socket for screen updates and writes them to stdout, using CSI ? 2026 h synchronized output for tear-free repaints.
- Watches SIGWINCH and forwards new sizes whenever the host terminal resizes.

When the loop exits, the client restores the original termios, emits the "disable mouse + show cursor" sequence, and returns control to your shell.

Detaching

There is no built-in keybind that means "detach this client". The client exits — releasing your terminal back to your shell — when any of these happen:

Trigger	Result
`Ctrl+D` on an empty line at the daemon's shell prompt	The shell exits, the pane exits. If it was the last pane in the session, the session ends and the client returns. Otherwise the daemon picks a new active pane and your client follows.
`kill -HUP <vmux-pid>`	The poll loop sees the closed stdin, sends `detach`, and returns.
`kill -TERM <vmux-pid>`	The process exits immediately; the daemon notices the dropped socket and removes the client.
The host terminal closes (close window, end of SSH session)	Same as `SIGHUP`: stdin returns EOF, the client sends `detach`, returns.
The session ends server-side (last pane exited)	The daemon sends `sessionEnded`, the client returns 0.

Because there is no detach keystroke, the standard idiom is "open vmux attach in its own terminal window or tmux pane, walk away by closing it, reattach later from any shell." The session keeps running.

# attach
vmux attach -s work

# in another terminal: drop the client out of band
pkill -HUP -f 'vmux attach -s work'

The session named work keeps running, with all its panes and processes intact, even after the client is gone.

Reattaching

vmux attach -s work

Reattach is the same call as initial attach. The daemon has been holding the session and pushes a fresh full-screen reset frame so your terminal redraws from scratch. Cursor position, scrollback within the visible area, and the active pane all carry over.

Multi-client (mirroring)

You can attach two vmux attach -s NAME calls to the same session at the same time. Both clients receive the same screen frames; both clients can send keystrokes; both keystroke streams are forwarded to the active pane in arrival order. There is no takeover mode — multi-attach is always mirror.

This is useful for pair work where one shell is on your laptop and the other is forwarded over SSH:

# Local
vmux attach -s pair

# On a second machine, after `ssh me@host`
vmux attach -s pair

It is also how the visionOS, Mac, and CLI clients can all observe the same session simultaneously.

If two clients have different terminal sizes, the daemon adopts the most recently sent size. Wrapping and rewriting follow that size until the next resize event. There is no per-client viewport; everyone sees the same buffer.

Examples

# attach to "default", auto-creating it if missing
vmux attach

# attach to a named session
vmux attach -s work

# bare invocation, equivalent to "attach"
vmux

# explicitly create-and-attach via new-session
vmux new-session -s build

# attach against a non-default daemon
vmux --socket /tmp/vmux-test.sock attach -s smoke

# attach using a project-pinned config
VMUX_CONFIG=~/.config/vmux/project-a.json vmux attach

Exit codes

Code	Meaning
0	Clean detach or session ended cleanly.
1	Anything thrown out of the client — connect failure, daemon launch failure, protocol error. The error string is written to stderr prefixed `vmux: …`.