Spaces, panes, and layouts

Use Spaces to separate projects, tabs to switch terminals, and panes to see terminals side by side.

The pieces of a workspace

Space

A named workspace that owns managed sessions and saves their arrangement. A session belongs to one Space at a time.

Session

A unit managed by pmuxd, with terminal programs and, when named for an agent, a mailbox.

Tab

A terminal view in the desktop window. A session's internal windows and panes are also visible through pmux ls.

Pane

A terminal region inside a tab. Split panes let you view more than one program at a time.

Create, save, and open Spaces

pmux space ls
pmux space create project
pmux space save project
pmux space open project
pmux space open project --new-window

The desktop Spaces rail provides the same project switch. A saved Space records the layout and session information. Opening it reconnects to live managed sessions when available.

For a saved Space with configured startup commands, --no-run skips those commands:

pmux space open project --no-run

Arrange panes

Use the command palette to find split, layout, and arrange actions. The available controls depend on the current chrome layout. Default shortcuts include:

• Ctrl + Shift + E: split right.
• Ctrl + Shift + D: split down.
• Ctrl + Alt + an arrow: move focus between panes.
• Ctrl + Shift + Z: expand the focused pane, then restore it.

To retile a managed session's first window from the CLI:

pmux arrange work grid
pmux arrange work even-h
pmux arrange work main-vertical

Use pmux ls for current IDs before moving panes with break-pane or join-pane. A desktop tab and a session's internal window are different objects; use the IDs reported by the command you are calling.

Blank terminals and restoration

A blank terminal belongs to its desktop window rather than a named managed session. The command palette offers explicit blank-tab and blank-split actions. Moving a blank terminal through its pane context menu preserves the running shell, directory, and scrollback.

Blank-terminal restoration is optional and off by default. When enabled, it saves the layout, pane sizes, directories, and focus. A later launch starts fresh shells; it does not restore the old environment or scrollback.