cmux-tui

cmux-tui is the Rust TUI multiplexer in this repository. It keeps a tmux-style tree of workspaces, screens, split panes, and tabs, uses Ghostty's VT engine for PTY state, and exposes the same state over a JSON-lines control socket for attach clients and other frontends.

Documentation

• Docs index
• Getting started
• Concepts
• Keyboard
• Mouse
• Configuration
• Machines and remote sessions
• Control socket protocol
• Browser panes

Build

Builds need Zig 0.16.0, a Rust toolchain, and the ghostty submodule initialized. The ghostty-vt-sys crate builds libghostty-vt.a from the submodule with Zig before compiling the Rust crates.

cd cmux-tui
cargo build -p cmux-tui

Run

machine-agent is available only on Unix platforms.

cd cmux-tui
cargo run -p cmux-tui
cargo run -p cmux-tui -- --session agents
cargo run -p cmux-tui -- --headless --session agents
cargo run -p cmux-tui -- attach --session agents
cargo run -p cmux-tui -- machine-agent --session agents
cargo run -p cmux-tui -- attach --session agents --surface <surface-id>

The default session is main. Default sockets live at $TMPDIR/cmux-tui-<uid>/<session>.sock; use --socket <path> for an explicit path. Detach from an attached TUI with prefix d, which is Ctrl-b d by default.

Pane layout stays tiled by default. Press Ctrl-b g to append a terminal to the right at two-thirds of the viewport width. The existing layout keeps its width, so a continuous horizontal scrollbar appears in the status bar. Focusing a pane reveals it with an animated viewport movement. Alt-n reapplies Zellij's automatic layout inside the focused horizontal column. Ctrl-b U undoes the latest structural layout action on the focused screen; undoing pane creation asks for confirmation before closing the pane.

attach --surface <id> attaches one PTY terminal by numeric or short surface id. It uses the full host terminal without the sidebar, status bar, pane border, or other tabs.

Packaged builds can run as npx cmux. The optional machine rail lets that local client switch among the current session, other Unix sockets, and sessions reached through SSH. It is disabled by default and activates when machine_sidebar.enabled is true or machines contains a valid entry in cmux-tui.json. npx cmux --cloud composes those local targets with the Cloud catalog and enables temporary machine connections without sending local SSH details to Cloud. The client uses noninteractive SSH with strict host-key checking and the remote cmux-tui relay --session <name> transport primitive, so the remote headless session, trusted host key, authentication key, and binary must already exist. See Machines and remote sessions.

npx cmux
npx cmux machine-agent --session agents
ssh -T dev@buildbox cmux-tui relay --session agents

The Unix-only machine-agent shares an existing local session through one outbound SSH registration with cmux.cloud. It prints a one-time pairing code and opens no listener. The final command carries raw JSON-lines protocol traffic and is normally started by the machine connector, not used as an interactive TUI.

Use --term <value> to set TERM for child PTYs. Without it, children get xterm-256color; CMUX_TUI_TERM can override the process default in the surface layer, with CMUX_MUX_TERM retained as a legacy fallback.

Browser Realism

By default, browser panes launch your real Google Chrome or another Chrome-family binary in browser.mode: "headful" with a visible window and a persistent per-session profile. Log into Google or other sites once in that visible window; cookies and logins persist across sessions. Set browser.mode: "headless" to hide the launched Chrome window. Both modes keep the anti-throttle flags, --disable-blink-features=AutomationControlled, the persistent --user-data-dir, and about:blank startup.

Chrome 136 and newer reject CDP remote debugging on the OS-default profile directory, and a running normal Chrome owns its profile SingletonLock. Use the mux profile, set browser.user_data_dir to a copy or a dedicated directory after quitting normal Chrome, or attach to a Chrome you started with --remote-debugging-port.

To attach instead of launching, set browser.cdp_url, CMUX_MUX_CDP_URL, or enable discovery. Agent Browser works the same way: run agent-browser get cdp-url and use the returned ws:// URL. This build supports ws:// and http:// CDP endpoints; wss:// is not supported.

Development

cd cmux-tui
cargo test

The smoke scripts expect a built cmux-tui binary unless CMUX_TUI_BIN is set.

cd cmux-tui
cargo build -p cmux-tui
python3 scripts/smoke-tui.py
python3 scripts/smoke-attach.py