Layout Modes

Tiling is a switch: on or off. When it is on, the panes follow one of three layouts. When it is off, the panes float and you place them yourself. Zoom sits on top of all of them and shows one pane large for a moment.

Try it live: the Layouts track lets you switch between them in your browser.

Open, close and focus panes below to see how each layout places them:

Switching modes

Turn tiling on or off:

Pick the layout from the command palette (Ctrl+P):

• Layout: BSP tiling
• Layout: master-stack
• Layout: scrolling (niri-style)
• Layout: disable tiling

Picking a layout also turns tiling on. There is no default key for a layout. Bind one yourself if you switch often.

The layout mode belongs to the session. It is kept in the daemon's session state, so a scrolling session is still scrolling after you detach and reattach, and turning tiling off does not forget which layout you had. The layout itself (the BSP tree, the scrolling columns) is kept per workspace, so each of the nine workspaces has its own.

startup.layout sets the mode a new session starts in: bsp, master-stack or scrolling. startup.tiled (default true) decides whether a new session starts tiled at all. A session that already exists keeps its own mode.

[startup]
layout = "scrolling"
tiled = true

From a script, tuios set-layout turns tiling on or off and tidies the splits:

tuios set-layout --tiling true
tuios set-layout --equalize
tuios set-layout --rotate

It needs an attached client.

Master-stack

The master-stack layout puts the first panes of a workspace in a master area and the other panes in a stack beside it. The master area is for the pane you work in most, such as an editor. The layout is close to dwm's tile layout and Hyprland's master layout.

With center, the first stack pane goes to the right, the next to the left, and so on. With only one stack pane, the master goes to the left. Two panes on a screen that is taller than it is wide stack one above the other.

Each workspace starts with these options. The keys below change the workspace on screen, and the workspace keeps the change. In a daemon session every attached client shows the same layout.

tuios set-layout --master-position center
tuios set-layout --masters 2

How a resize is kept

A resize goes into the workspace's splits: the master ratio, and the share of every other pane. That covers each master, each stack pane, and each row and pane of the grid. The keyboard resizes, the percentage resizes and a mouse drag on a divider all do this, so the resize survives a retile. A terminal resize is a retile too. When a pane opens or closes, the part of the layout it changes goes back to equal shares.

With the master in the center, a resize moves one divider, and the next retile puts the master back in the middle at its new width. The splits are session state, so every client attached to the session lays the workspace out the same way.

In every layout, a workspace keeps its splits when the session's size changes while the workspace is off screen. When you switch back, the panes fit the new size.

Scrolling

The scrolling layout is modeled on the niri window manager. Each pane is a column on a horizontal strip, and the screen is a window onto that strip. A new pane gets a new column right after the focused one, and the strip scrolls to show it. The other columns keep their width.

A column holds one pane by default. It can hold several stacked vertically, which split its height evenly. Closing the last pane in a column removes the column and moves focus to the column on its left.

Moving around

Moving focus with the keyboard scrolls the strip by the least amount that shows the whole focused column, with four cells of its neighbour peeking in beside it. It does not center the column: when all of it and that margin are already on screen, the strip stays put. Clicking a column that is partly off screen brings all of it on screen (appearance.niri_click_reveals). With focus_follows_mouse on, hovering does the same (appearance.niri_hover_reveals).

The plain mouse wheel belongs to the pane under the pointer. The strip only scrolls while Alt or Shift is held. This stops a trackpad's sideways drift from sliding the strip while you scroll a pane's history.

Column commands

These have palette entries and no default key. The action names can be bound in [keybindings].

A column's width is a share of the screen until you resize it with < or >, which pins it to a cell count. Each press changes the width by four cells, from 20 cells up to scroll_column_max. Cycling the width unpins it again.

Settings

The default column width of 55% is over half on purpose: two columns never quite fit, so the strip reads as something you scroll.

The scroll offset and the columns are part of the session. Every client attached to the session sees the same columns at the same offset, and the columns come back after a session switch or a reattach. A session switch forgot my column widths tells how the columns became session state.

Shared borders: with shared_borders on, columns draw no border of their own. One divider stands between two columns. Drag it to set the width of the column on its left. Windows stacked in one column have a divider between them too, but they always share the column's height evenly.

Limits: the strip always animates when it slides, even with animations off, because a jump is hard to follow.

Floating

With tiling off, panes float. Drag a pane by its title bar to move it, or Alt+drag anywhere on it. Right-drag resizes it from the nearest corner. In window management mode:

Dragging a pane to a screen edge or corner snaps it there too. See Keybindings.

The palette entry Toggle floating lifts only the focused pane out of the tiling and lets it float over the others. Run it again to put the pane back.

For a short-lived floating pane that closes when its program exits, use a popup:

tuios popup --width 90% --height 80% -- htop

Zoom

Zoom shows the focused pane over the layout. By default it takes 95% of the screen, so the edges of the layout stay visible around it. The layout underneath is not changed.

On a tiled pane, the third title bar control toggles zoom too (appearance.window_button_zoom).

Gaps and sizing

appearance.gap keeps empty cells between neighbouring panes, in every tiling mode (0 to 8, default 0). It is an inner gap only: there is no margin at the screen edge.

The layout prefix sizes the focused pane to a percentage:

Each percentage is its own action (resize_width_50 to resize_width_90, resize_height_50 to resize_height_90), so any of them can be rebound in [keybindings.layout_prefix]. The layout still applies its minimum pane size and gaps. In the scrolling layout only the width actions do anything.

gap, master_ratio, scroll_column_width and shared_borders decide how many cells each pane gets, so they are shared across the session: change one on any client and every attached client follows. Purely visual settings such as the theme, border style and glyphs stay per client.

Finding a pane

The palette entry All windows opens a searchable list of every pane on every workspace, with a short preview of each. It has no default key.

The preview is the first three non-empty lines of the pane, taken when the list opens. The directory is only read on Linux.

Typing into several panes

Multifocus sends your typing to several panes at once, like tmux's synchronize-panes. Use it to run the same command on several hosts.

The two actions have no default key. This example binds them to Ctrl+B y and Ctrl+B Y:

[keybindings.prefix_mode]
toggle_multifocus_active = ["y"]
toggle_multifocus_all = ["Y"]

To open many panes with multifocus on in one step, use tuios xpanes. It opens one pane per item on a new workspace, tiled, and puts all of them in the set:

tuios xpanes --ssh web1 web2 web3

From a script, tuios run-command SetMultifocus <window>... sets the set to exactly these windows. With no window, it empties the set.

Panes in the set get a distinct border colour. A notification shows the size of the set when you change it. With appearance.dim_unfocused on, the panes in the set are not dimmed. Set appearance.dim_multifocus = true to dim them like the other panes.

While the set is not empty and you are in terminal mode, every key that goes to the focused pane also goes to each pane in the set. A paste goes to each pane in the set too. A pane gets a bracketed paste only when its program turned bracketed paste on. A paste into a scrolled pane first returns it to live output, as a typed key does. In copy mode, TUIOS drops the paste. Keys that TUIOS handles itself, such as the leader key, are not copied.

Limits:

• Nothing is copied in window mode.
• A key goes only to the panes of the set that are on the current workspace and are not minimized. The other panes stay in the set and get keys again when they are on screen.
• The set belongs to your client. Other clients do not share it. It does not survive a detach, and a session switch clears it.
• The set follows panes, not positions. A swap keeps the same panes in the set. A pane that closes leaves the set.
• A popup cannot join the set.

Multi copy mode

Multi copy mode is copy mode on every pane of the multifocus set at the same time. Use it to search the output of many panes at once and copy the same part from each pane. Each pane has its own cursor and its own selection. Each key moves all of them together.

To start it, add two or more panes to the multifocus set and focus one of them. Then press Ctrl+B [, the copy mode key. When the focused pane is not in the set, the key starts copy mode on one pane. When multifocus is on, the palette entry Multi copy mode also starts it, and the prefix menu shows Multi copy (N) on the [ line.

The dock shows MULTI 3, where 3 is the number of panes. After a search, it shows MULTI 2/3: the search found text in 2 of the 3 panes.

A pane where the search finds no text loses the multifocus border colour. With a theme, the pane is also dimmed. It keeps its cursor. It takes no motions or selections until a later search finds text in it. Ctrl+L clears the search.

y copies only the selected text of each pane. A pane without a selection adds nothing. The panes are in window order.

The format starts as appearance.selection.multi_format (default plain). Tab changes it until you leave multi copy mode.

appearance.selection.copy_command and a [[keybindings.copy_pipe]] key also work in multi copy mode. The command gets the text that y copies, in the current format, one time for all panes. See Pipe a yank through a command.

Y opens a prompt at the bottom of the focused pane. The default path is ~/tuios-copy-<date>-<time>.<ext>, with txt, md or json for the format. Type or paste a path. Press Enter to save, or Esc to cancel.

• A relative path starts in the directory of the focused pane, when its shell reports one. Otherwise it starts in your home directory. The line above the prompt shows the full path.
• TUIOS does not write over a file that exists. It tells you when the folder does not exist or when the path is a folder.
• The dock shows the path of the file it wrote. In the web client and over SSH, the file is on the machine that runs TUIOS, and the dock names that machine.

A pane title can come from a remote shell. In the markdown and json formats, TUIOS removes control, bidirectional and zero-width characters from the title and cuts it to 200 characters.

Limits:

• Soft-wrapped lines are joined by a width estimate, as in copy mode on one pane.
• Multi copy mode ends when focus moves to a pane that is not in it.
• A pane that you minimize or move to another workspace leaves multi copy mode.
• The clipboard gets the copy through OSC 52. Some terminals cut a long OSC 52 copy. Above 100 KB, the dock tells you. Use Y to save a large copy to a file.

Related