BSP Tiling

Tile windows with binary space partitioning, and switch to the master-stack or scrolling layouts.

When tiling is on, TUIOS arranges windows for you so they never overlap. The default layout is BSP (binary space partitioning): every new window splits an existing one in two, so the screen becomes a tree of splits you can reshape with the keyboard or the mouse.

All keys on this page are for window management mode unless they start with Ctrl+B, which works in both modes. On macOS, read Alt as Opt.

Turning tiling on and off

New sessions start tiled. To switch it:

Key	Where
t	Window management mode
Ctrl+B Space	Any mode
Ctrl+B t t	The window prefix menu

Tiling is on or off for the whole session. When it is off, windows float: you move and resize them freely, and h, l and f snap the focused window to the left half, the right half or the full screen.

While tiling is on, the dock shows the tiling icon followed by V or H: the direction the next split will take.

startup.tiled = false in the configuration makes new sessions start floating.

Layout modes

Tiling uses one of three layouts:

Layout	How windows are arranged
BSP (default)	A tree of splits. Any number of windows, each resizable on its own.
Master-stack	One window: full screen. Two: side by side, or stacked on a tall screen. Three: a master window on the left and two stacked on the right. Four or more: a grid, two columns wide up to six windows and three beyond.
Scrolling	Niri-style columns on a strip wider than the screen. New windows add a column and the view scrolls, instead of every window shrinking.

There is no default key for switching layouts. Open the command palette (Ctrl+P) and run one of:

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

Choosing a layout turns tiling on if it was off. The layout belongs to the session and survives detaching; turning tiling off and on again brings the same layout back. startup.layout sets the layout new sessions start with: bsp, master-stack or scrolling.

Next layout and Previous layout in the palette do something else: they cycle through your saved layout templates.

The rest of this page is about BSP. The scrolling layout's keys and commands are described in the repository's LAYOUT_MODES.md.

How new windows are placed

A new window splits the focused one. Which way it splits depends on the tree's insertion scheme:

Scheme	Rule
spiral (default)	Alternate vertical and horizontal by the depth of the window being split, like bspwm. Repeatedly splitting the newest window spirals inward.
longest_side	Split across the longer side of the window.
alternate	Alternate vertical and horizontal by the total number of splits in the tree.
smart_split	Split vertically when the window is more than twice as wide as it is tall, horizontally when it is taller than wide, and otherwise by depth.

A new workspace starts with the scheme in appearance.tiling_scheme (default: spiral). A workspace that already has windows keeps its own scheme. Changing the option does not move it.

Set the option in config.toml, on the settings page (Ctrl+B ,), or with tuios set-config appearance.tiling_scheme <scheme>.

To change a workspace's scheme directly, run Cycle tiling scheme in the command palette, or one of the Set tiling scheme: ... rows. Their action names are cycle_tiling_scheme and set_tiling_scheme_spiral, set_tiling_scheme_longest_side, set_tiling_scheme_alternate, set_tiling_scheme_smart_split, in case you want to bind one. None of them ships with a default key.

A layout template still saves its own scheme (tiling_scheme). Loading a template that carries one sets it too.

Smart split in the command palette splits the focused window once with the smart_split rule, whatever the tree's scheme. Its action name is smart_split if you want to bind it.

Splitting

A split opens a new window beside the focused one.

Key	Prefix form	Action
-	Ctrl+B -	Split horizontally: the new window goes below
| or \	Ctrl+B |	Split vertically: the new window goes to the right
R	Ctrl+B R	Rotate the split holding the focused window, so side by side becomes stacked and back
=	Ctrl+B =	Equalize: set every split back to half and half

tuios split-window left, right, up and down put the new window on that side. (Added in v0.10.0)

TUIOS refuses a split that leaves a window smaller than 20 columns by 5 rows, and says why. (Added in v0.10.0)

A split creates the window at once. There is no empty slot waiting to be filled, so pressing n after a split adds a third window.

Preselection

Preselection chooses where the next window goes, relative to the focused one, without creating it yet.

Key	Next window appears
Alt+h	Left
Alt+j	Below
Alt+k	Above
Alt+l	Right

It only applies while tiling is on, and the next new window uses it up. There is no key to cancel a preselection. It stays until a window is created, or until a split key replaces it with its own direction.

Moving focus and swapping

Key	Action
h / l	Focus the window to the left / right
Alt+arrow, or Ctrl+B then an arrow	Focus the window in that direction, in either mode
H or Ctrl+←	Swap with the window to the left
J or Ctrl+↓	Swap with the window below
K or Ctrl+↑	Swap with the window above
L or Ctrl+→	Swap with the window to the right

A swap exchanges two windows without changing the shape of the tree. If there is no window in that direction, nothing happens.

Moving a window with the mouse

Drag a window by its title bar, or Ctrl+click anywhere in it and drag. The place where you release it on another window sets the result:

Drop on another window	Result
Its middle	The two windows swap places.
Its left, right, top or bottom edge (Added in v0.9.3)	That window splits in two. The dragged window takes the half on that edge. The window that shared a split with the dragged window fills the space it left. The new split uses the default ratio.

An edge is the outer quarter of that side of the window.

• While you drag, TUIOS highlights the area where the window will go. The highlight shows when the pointer stays on one zone for a short time.
• The highlight is a pane frame in the accent colour, with the same border glyphs as the panes. Inside it, the text fades into one even tint. On a 16-colour terminal the frame is reverse video. (Added in v0.10.0)
• When the layout changes under a held drag, for example when a pane closes, the highlight moves with it. (Added in v0.10.0)
• A press of another mouse button during the drag cancels it. The window goes back to where it was. (Added in v0.10.0)
• A window that is too small to hold two windows on one axis has no edges on that axis.
• A drop on the edge where the window already is changes nothing.
• A drop on no window puts the window back where it was.
• The master-stack and scrolling layouts always swap. They show no highlight.
• While a window is zoomed, or a scratch group shows, a drop always swaps.

The new layout is session state. Every client attached to the session gets it, and it stays after a reattach.

appearance.drop_preview sets how the highlight looks: fill (the default), outline or off. appearance.drop_preview_delay sets how long the pointer stays on a zone before the highlight shows, 120ms by default. These options do not change the drop. See Tiling and zoom.

Resizing

Each key moves one edge of the focused window. Every window that shares that edge moves with it.

Key	Edge	Step
>	Right edge, outward	4 columns
<	Right edge, inward	4 columns
.	Left edge, outward	4 columns
}	Bottom edge, down	2 rows
{	Bottom edge, up	2 rows
]	Top edge, up	2 rows
[	Top edge, down	2 rows

A window cannot shrink below 20 columns or 5 rows, and an edge already at the screen border cannot move outward. If a key does nothing, try the opposite edge: . instead of > for a window on the right side of the screen.

Warning

There is no default key to move the left edge inward. , would be the natural one, but it opens the settings page. Bind the resize_master_shrink_left action to a free key if you want it.

To resize with the mouse, drag a window's border. With shared borders on, drag the divider line between two windows.

In master-stack, the same keys move the edge by 4 columns, as in any tiled layout. The master window's default share of the screen is set with appearance.master_ratio (30 to 70, default 50) or on the settings page.

Resizing to a percentage

The layout prefix sizes the focused window to a share of the screen:

Keys	Action
Ctrl+B L then 5 to 9	Width to 50% to 90%
Ctrl+B L then Shift+5 to 9	Height to 50% to 90%

The layout still keeps every window at its minimum size, so you get the requested share wherever the neighbours allow it.

How a resize is stored

A resize moves the window rectangles first, then recomputes every split ratio in the tree from the result. Ratios are what the tree keeps, so a resize survives later retiling, detaching and reattaching. Split ratios in BSP have no fixed range; only master-stack's appearance.master_ratio setting is limited to 30% to 70%.

Shared borders

By default each window draws its own border, so two tiled windows show two lines between them. Shared borders draw a single line instead, and leave more room for content.

Config	appearance.shared_borders = true
Default	off
Flag	--shared-borders
In the app	the settings page, or Toggle shared borders in the command palette

[appearance]
shared_borders = true

Shared borders apply in every layout: BSP, master-stack and scrolling.

With shared borders on, the pointer changes shape over a divider, and dragging it moves the divider.

Note

The divider takes one cell, and it comes out of the right or bottom window. With a 160-column screen split in half, the left window is 80 columns wide and the right one 79. This is expected, and = does not change it.

appearance.gap adds empty cells between neighbouring windows, in every layout.

Layout templates

A template saves the current arrangement so you can restore it later.

Key	Action
Ctrl+B L s	Save the layout, after asking for a name
Ctrl+B L l	Load a layout from a searchable list

The same two are in the command palette as Save layout and Load layout, and Next layout and Previous layout cycle through saved templates. A template records window positions, workspaces, working directories, startup commands and the insertion scheme. Layout load starts each new window in its folder. It does not type a cd into a new window.

From the shell:

tuios layout list            # list saved templates
tuios layout dir             # print the templates directory
tuios layout export mysetup  # print a template as a tape script
tuios layout delete mysetup  # delete a template

With tiling off, Ctrl+B L then 1 to 4 snaps the focused window to a corner: top left, top right, bottom left, bottom right.

Persistence

Each workspace has its own BSP tree. The trees are part of the session, so they survive detaching, and the daemon saves them to disk so they come back after a restart. See Sessions for what else a restart keeps.

If a tree goes stale, for example because it still names a window that has closed, TUIOS rebuilds it from the current windows and keeps their proportions.

Troubleshooting

Windows are not tiling

Check the dock for the tiling icon with V or H. If it is not there, press t.

If windows are arranged but not as BSP would arrange them, you are in master-stack or scrolling. Run Layout: BSP tiling from the command palette.

A resize key does nothing

The edge is at the screen border, or moving it would shrink a window below 20 columns or 5 rows. Use the key for the opposite edge. , opens settings and never resizes.

The layout looks lopsided

Press = to set every split back to half and half.

A new window appeared in the wrong place

A preselection was still set. It lasts until a window uses it, and a split key replaces it: pressing - after Alt+l puts the window below, not to the right.

Related

• Keybindings: Every default key
• Configuration: Shared borders, gaps and layout settings
• Sessions & Daemon Mode: What survives detaching and restarts
• Architecture: Where the layout code lives