TUIOS implements automatic window tiling using Binary Space Partitioning (BSP), an algorithm that recursively divides screen space to fit windows efficiently. Unlike rigid grid-based tiling, BSP adapts to any number of windows and allows fine-grained control over splits.
Note: Throughout this document,
Ctrl+Brefers to the default leader key. This is configurable via theleader_keyoption in your config file.
- Overview
- Basic Tiling
- BSP Concepts
- Manual Split Control
- Preselection
- Window Swapping
- Resizing in BSP Mode
- Advanced Operations
- Practical Workflows
- Technical Implementation
BSP tiling automatically arranges windows in a tree structure where each node represents either a window or a split (horizontal or vertical). When you create a new window, TUIOS intelligently decides where to place it based on the current layout.
Key advantages over grid tiling:
- Works with any number of windows (not limited to 2, 4, 6, etc.)
- Each window can have a different size
- Full control over split direction at any level
- Persistent per-workspace configuration
In Window Management Mode, press:
t # Toggle tiling on/off
Ctrl+B Space # Alternative: prefix + Space
Or use prefix commands:
Ctrl+B t t # Via tiling prefix menu
The status bar shows "TILING" when enabled.
When tiling is enabled, TUIOS automatically positions new windows:
- First window: Takes full screen
- Second window: Splits vertically (side-by-side)
- Third window: Splits horizontally (top/bottom on right side)
- Fourth+ windows: Spiral pattern (alternating V/H splits)
This spiral layout balances screen space naturally as you add windows.
Press t again to disable tiling. Windows remain in their current positions but can be dragged freely.
Internally, TUIOS maintains a binary tree for each workspace:
Root Split (Vertical)
├── Window 1 (left half)
└── Split (Horizontal)
├── Window 2 (top-right quarter)
└── Window 3 (bottom-right quarter)
Each split has a direction (vertical or horizontal) and a ratio determining how space is divided.
The dock shows the next split direction when tiling is active:
V- Next window splits vertically (left/right)H- Next window splits horizontally (top/bottom)
This helps you predict where the next window will appear.
Each workspace maintains its own BSP tree. Switching workspaces preserves the tiling configuration on both sides.
Rather than relying on automatic placement, you can manually split the focused window.
In Window Management Mode with a window focused:
Ctrl+B - # Split horizontally (current window → top/bottom)
Ctrl+B | or \ # Split vertically (current window → left/right)
This divides the focused window's space in half, placing the focused window in one half and preparing space for a new window in the other half.
Example workflow:
# Create first window
n
# Split it vertically
Ctrl+B |
# Create new window (appears in right half)
n
# Focus left window and split horizontally
Tab
Ctrl+B -
# Create new window (appears below left window)
n
Result: Three windows in an L-shaped layout.
To change an existing split's direction:
Ctrl+B R # Rotate split at focused window
This toggles the split containing the focused window between vertical and horizontal. Useful for reorganizing layouts without recreating windows.
Example:
Start with side-by-side windows (vertical split):
┌─────┬─────┐
│ A │ B │
└─────┴─────┘
Focus either window and press Ctrl+B R:
┌───────────┐
│ A │
├───────────┤
│ B │
└───────────┘
Now they're stacked (horizontal split).
Preselection lets you control where the next window spawns relative to the focused window. Think of it as pre-deciding the split direction before creating a window.
In Window Management Mode:
Ctrl+B Shift+H # Next window appears left of focused
Ctrl+B Shift+L # Next window appears right of focused
Ctrl+B Shift+K # Next window appears above focused
Ctrl+B Shift+J # Next window appears below focused
After preselecting, create a window normally with n. The preselection is consumed and resets.
Example: Creating a sidebar layout
# Start with one window
n
# Preselect left
Ctrl+B Shift+H
# Create narrow sidebar on left
n
# (resize the split to make sidebar narrow)
<
# Focus main window and preselect below
Tab
Ctrl+B Shift+J
# Create terminal below main area
n
Result: Sidebar on left, main area on right with terminal below it.
Without preselection, TUIOS uses its default spiral algorithm. With preselection, you override this for precise control.
Preselection is particularly useful for:
- Creating asymmetric layouts
- Building UI patterns (sidebar + main + footer)
- Inserting windows into specific locations in complex layouts
Once windows are tiled, you can rearrange them without changing the underlying split structure.
In Window Management Mode:
Shift+H or Ctrl+Left # Swap with window to the left
Shift+L or Ctrl+Right # Swap with window to the right
Shift+K or Ctrl+Up # Swap with window above
Shift+J or Ctrl+Down # Swap with window below
Swapping exchanges two windows' positions in the BSP tree while preserving their sizes.
Note the difference:
h/j/k/lor arrow keys: Move focus between windowsShift+H/J/K/LorCtrl+arrows: Swap windows
Mouse users can drag windows in tiling mode. Dragging a window onto another swaps them.
BSP allows resizing along any split boundary.
The master ratio controls the size of the main window area (typically the leftmost window):
> or Shift+. # Grow master area (from right edge)
< or Shift+, # Shrink master area (from right edge)
. (period) # Grow master area (from left edge)
, (comma) # Shrink master area (from left edge)
Adjustment increment: 5% per keypress.
Control the vertical split ratio of the focused window:
} or Shift+] # Grow height (from bottom edge)
{ or Shift+[ # Shrink height (from bottom edge)
] (right bracket) # Grow height (from top edge)
[ (left bracket) # Shrink height (from top edge)
The distinction between left/right and top/bottom edge resizing matters:
From right edge (< / >):
- Moves the right boundary of the master area
- Affects right-side windows
From left edge (, / .):
- Moves the left boundary of the master area
- Affects left-side windows
This allows fine control in complex layouts where multiple splits exist.
Resizing modifies the split ratio at the nearest split node. TUIOS walks up the tree to find the appropriate split to adjust.
For example, if you have:
┌────┬────┐
│ A │ B │
├────┼────┤
│ C │ D │
└────┴────┘
With window B focused, pressing > grows the right column (B and D together) at the expense of the left column (A and C).
To reset all splits to equal proportions:
Ctrl+B = # Equalize all splits
This sets all split ratios to 50/50 throughout the entire tree, giving all windows equal space based on their position in the tree.
Useful when you've made many resize adjustments and want to start fresh with balanced spacing.
When you manually create splits and preselect positions, TUIOS marks the workspace as having a "custom layout". This layout persists even when you close windows.
To fully reset a workspace's layout:
- Close all windows
- Toggle tiling off and on
- Create new windows
You can disable tiling to temporarily drag windows freely, then re-enable tiling. Windows return to their tiled positions.
This is useful for:
- Quickly maximizing a window for focus (press
f) - Moving a window to a second monitor temporarily
- Overlapping windows for comparison
Classic three-pane layout (editor + terminal + docs).
# Start tiling
t
# Create editor window
n
i
vim main.go
Enter
Ctrl+B d
# Preselect right for terminal
Ctrl+B Shift+L
n
i
go run .
Ctrl+B d
# Focus terminal and preselect below for logs
Tab
Ctrl+B Shift+J
n
i
tail -f logs/app.log
Result:
┌──────────┬──────────┐
│ │ Terminal │
│ Editor ├──────────┤
│ │ Logs │
└──────────┴──────────┘
For ultrawide monitors, create a three-column layout.
t
n # First window (full)
Ctrl+B | # Split vertically
n # Second window (right)
Tab # Focus first (left)
Ctrl+B | # Split left side vertically
n # Third window (middle)
# Adjust widths for 1:2:1 ratio
Tab Tab # Focus rightmost
<< # Shrink right column
Tab Tab # Focus leftmost
.. # Shrink left column
Result: Left sidebar, main area, right sidebar.
Four equal quadrants.
t
n
n
n
n
Ctrl+B = # Equalize all splits
Result:
┌─────┬─────┐
│ 1 │ 2 │
├─────┼─────┤
│ 3 │ 4 │
└─────┴─────┘
Main presentation area with hidden notes.
t
n # Main window
Ctrl+B Shift+J # Preselect below
n # Notes window
{{{{{ # Shrink notes to minimal height
Result: Full screen presentation with a thin strip of notes at bottom.
Vertically stacked log viewers.
t
n # First log
Ctrl+B - # Split horizontally
n # Second log
Ctrl+B - # Split horizontally again
n # Third log
Ctrl+B = # Equal height
Result: Three equal horizontal strips.
Each workspace maintains a BSPTree with nodes of two types:
- Leaf nodes: Contain a window ID
- Internal nodes: Contain split direction (H/V), ratio (0.0-1.0), and two child nodes
Default scheme: layout.AutoScheme set to spiral pattern.
When auto-tiling:
- First window → root leaf
- Second window → root becomes vertical split, two leaves
- Third+ windows → finds the largest window, splits it (alternating directions)
Each internal node stores a ratio (default 0.5). This represents the fraction of space given to the left/top child. Ratio range: 0.3 to 0.7 (enforced to prevent unusable layouts).
Windows are assigned stable integer IDs for BSP tracking (independent of UUID). This mapping persists across window focus changes and allows the BSP tree to track windows even as they're rearranged.
When you perform operations:
- Split: Replaces leaf node with internal node containing two new leaves
- Swap: Exchanges leaf nodes at two tree positions
- Rotate: Changes internal node's direction flag
- Equalize: Walks tree, sets all ratios to 0.5
- Resize: Finds nearest parent split in the resize direction, adjusts ratio
After tree modifications, TUIOS walks the tree recursively, calculating rectangles:
- Start with workspace dimensions
- At each split node, divide rectangle by ratio and direction
- At each leaf node, assign rectangle to corresponding window
- Apply all window geometry in a single batch
This prevents flicker and ensures atomic layout updates.
Each workspace stores:
WorkspaceTrees[workspaceNum]- BSP tree structureWorkspaceMasterRatio[workspaceNum]- Master ratio for resizingWorkspaceHasCustom[workspaceNum]- Whether user made manual splits
When you switch workspaces, trees are preserved. When daemon mode is active, BSP state is serialized and restored across sessions.
Check tiling is enabled: Status bar should show "TILING". Press t to toggle.
Check workspace: Each workspace has independent tiling state. Switching workspaces may land you on a workspace with tiling disabled.
Too many windows: BSP handles any number of windows, but with 10+ windows, individual window size becomes impractical. Consider using multiple workspaces.
Reset to balanced layout:
Ctrl+B = # Equalize all splits
Verify focused window: Resize operations affect the split containing the focused window. Make sure the correct window is focused.
Check direction: Swap commands are directional. If there's no window in the specified direction, nothing happens.
Try mouse drag: Mouse dragging always swaps if you drag one window onto another.
Preselection is one-time: After creating a window, preselection resets. You need to preselect again for the next window.
Cancel preselection: Press Esc in Window Management Mode to cancel a preselection without creating a window.
Check dock indicator: The dock shows V or H for the next split direction when tiling is active.
Visualize the tree: Run Ctrl+B D l to see debug logs, which include BSP tree structure.
- Keybindings Reference - Complete keybinding list for tiling
- Configuration Guide - No BSP-specific configuration currently, but keybindings are customizable
- Architecture Guide - Technical details on BSP implementation (see
internal/layout/bsp.go)
Grid tiling (not used in TUIOS):
- Fixed positions (1, 2, 3, 4... windows fit in grid cells)
- Wasted space with odd numbers of windows
- Predictable but inflexible
BSP tiling (TUIOS):
- Recursive splits adapt to any number
- No wasted space
- Full control over layout
Some window managers require you to manually tile every window. TUIOS offers both:
- Auto-tiling for quick layouts
- Manual splits and preselection for precise control
You can mix approaches: start with auto-tiling, then use manual splits to refine.
Potential future additions to BSP tiling:
- Named layouts (save/restore BSP configurations)
- Per-workspace split defaults
- Visual split indicators in the terminal
- Ratio presets (e.g., 30/70 split for sidebar layouts)
Check the GitHub issues for tracking and discussion.