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 tilingLayout: master-stackLayout: 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 always starts with spiral. There is no config option or key for the scheme. It is saved in layout templates (tiling_scheme), so loading a template that carries one is how you change it.
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 |
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. Dragging a window onto another with the mouse also swaps them.
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.
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 = trueShared borders apply to BSP and master-stack. The scrolling layout always draws a border per window.
With shared borders on, the pointer changes shape over a divider, and dragging it moves the divider.
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.
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 templateWith 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.