Workspaces & Panes

A workspace is a saved arrangement of subshell panes: several agents side by side in one view, the way you would arrange terminals on a large monitor, but stored and reachable from any device. Each pane holds exactly one subshell; splits nest as deep as you want.

Tiling on a wide screen, tabs on a narrow one

The same workspace answers to two presentations, and the screen decides which one it gets:

• 1024px or wider: a tiling layout. Panes divide the space, nothing overlaps, and dividers are draggable.
• Below 1024px: tabs. One subshell at a time, sized for the device you are holding.

The tab view never writes the stored layout, so a quick look from your phone cannot flatten the arrangement you built on a desktop. Switch back to a wide window and the tiling is exactly where you left it.

Adding panes

Every way to add a pane leads to the same choice (put an existing subshell here, or create a new one) and a placement: split right, split down, or as a tab beside the focused pane.

• The workspace header's Add subshell opens the picker for the focused pane.
• Each subshell page has a Split button: it opens the picker already filled with the same agent, machine, and folder, and puts the new pane beside the one you were looking at.
• Drag a subshell from the sidebar onto the workspace and it lands as a right-hand split of the focused pane. Within a workspace a subshell holds at most one pane (dropping one that is already open there just focuses its pane), though the same subshell may also sit in other workspaces.

Splitting always starts a new unsaved workspace beside whatever you were looking at, even when the subshell already lives in one you saved, which stays untouched. The draft is yours to keep with Save as workspace, which is only naming it; an unsaved workspace that drops back to a single pane is discarded, because there is nothing left to arrange.

Moving, closing, and what survives

Drag a pane's tab to split another group or dock it as a tab, and the terminal inside is relocated, not reconnected: the layout manager keeps every visible pane's stream alive through moves and resizes, so no restart, no replay, no lost keystrokes. A tab you send to the background is the deliberate exception: it releases its terminal so a hidden pane streams to no one, and returning replays it from scrollback, fresh.

Closing needs a distinction, because two controls look similar and are not:

• A pane tab's × removes the pane. The subshell keeps running and remains in your list; put it back into a workspace whenever you like.
• Close on a maximized pane closes the subshell itself: it stops the process and deletes it, with a confirmation, exactly like the subshell menu's Close. Deleting a subshell takes its panes out of every workspace with it.

One more control worth knowing: maximize (the corner icon on a group's header) gives one pane the whole space, and while maximized you get that pane's transcript search.

One pane, one size across every device

A tmux pane has exactly ONE grid; your split, your sizing, everyone's view. When several devices are attached to the same subshell, the server sizes the pane so the smallest visible one can display all of it. The reasoning, the exceptions, and how to pin the size to one screen are on Devices. If the subshell is shared, that is also why you can see who else is attached: the same single-grid rule makes it impossible to explain the pane's size without naming the devices.

See also

• Subshells: the pane's resident process and its lifecycle
• Devices: why the pane is the size it is
• Sharing: what others see when you share a workspace pane

Edit on GitHub