BSP Tiling - TUIOS

Overview

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.

Throughout this guide, Ctrl+B refers to the default leader key. This is configurable via the leader_key option in your config file.

Key Advantages

Flexible Layout

Works with any number of windows, not limited to powers of 2

Custom Sizing

Each window can have a different size based on your needs

Manual Control

Full control over split direction at any level of the tree

Persistent State

Per-workspace configuration survives sessions

Enable Tiling

Toggle tiling mode in Window Management Mode:

t                    # Toggle tiling on/off
Ctrl+B Space         # Alternative: prefix + Space
Ctrl+B t t           # Via tiling prefix menu

The status bar shows “TILING” when enabled.

Auto-Tiling Behavior

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.

The dock shows the next split direction when tiling is active: V (vertical) or H (horizontal). This helps predict where the next window will appear.

BSP Concepts

The Split Tree

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:

Direction: Vertical (left/right) or Horizontal (top/bottom)
Ratio: How space is divided (default 0.5 = 50/50)

Per-Workspace State

Each workspace maintains its own BSP tree. Switching workspaces preserves the tiling configuration on both sides. See Workspaces for details on multi-workspace usage.

Manual Split Control

Rather than relying on automatic placement, you can manually split the focused window:

Create Splits

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.

Create first window

Press n in Window Management Mode

Split it vertically

Press Ctrl+B |

Create new window

Press n - appears in right half

Focus left and split horizontally

Press Tab to focus left window, then Ctrl+B -

Create third window

Press n - appears below left window

Result: Three windows in an L-shaped layout.

Rotate Split Direction

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.

┌─────┬─────┐
│  A  │  B  │
└─────┴─────┘
Vertical split (side-by-side)

Preselection

Preselection lets you control where the next window spawns relative to the focused window.

Preselection Commands

Alt+h                # Next window appears left of focused (Linux)
Alt+l                # Next window appears right of focused
Alt+k                # Next window appears above focused
Alt+j                # Next window appears below focused

On macOS, use Option+h/j/k/l instead of Alt.

After preselecting, create a window normally with n. The preselection is consumed and resets.

Preselection Workflow

Creating a sidebar layout:

Start with one window

Press n to create initial window

Preselect left

Press Alt+h (or Ctrl+B Shift+H)

Create narrow sidebar

Press n - new window appears on left

Resize sidebar

Press < multiple times to make sidebar narrow

Focus main window and preselect below

Press Tab then Alt+j

Create terminal below

Press n - appears below main area

Result: Sidebar on left, main area on right with terminal below it.

Preselection is particularly useful for:

Creating asymmetric layouts
Building UI patterns (sidebar + main + footer)
Inserting windows into specific locations in complex layouts

Window Swapping

Rearrange windows without changing the underlying split structure:

Swap Commands

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.

Focus vs Swap:

h/j/k/l or arrow keys: Move focus between windows
Shift+H/J/K/L or Ctrl+arrows: Swap windows

Mouse users can drag windows in tiling mode - dragging one window onto another swaps them.

Resizing in BSP Mode

BSP allows resizing along any split boundary.

Master Ratio Adjustment

Control 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.

Height Adjustment

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)

Edge-Based Resizing

The distinction between edges matters in complex layouts:

Right Edge (< / >)

Moves the right boundary of the master area, affects right-side windows

Left Edge (, / .)

Moves the left boundary of the master area, affects left-side windows

Bottom Edge ({ / })

Moves the bottom boundary of focused window

Top Edge ([ / ])

Moves the top boundary of focused window

This allows fine control in complex layouts where multiple splits exist.

Equalize Splits

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.

Useful when you’ve made many resize adjustments and want to start fresh with balanced spacing.

Practical Workflows

Workflow 1: Development Environment

Classic three-pane layout (editor + terminal + logs):

# Start tiling
t

# Create editor window
n
i
vim main.go
Ctrl+B d

# Preselect right for terminal
Alt+l    # or Ctrl+B Shift+L
n
i
go run .
Ctrl+B d

# Focus terminal and preselect below for logs
Tab
Alt+j    # or Ctrl+B Shift+J
n
i
tail -f logs/app.log

Result:

┌──────────┬──────────┐
│          │ Terminal │
│  Editor  ├──────────┤
│          │   Logs   │
└──────────┴──────────┘

Workflow 2: Wide Monitor Layout

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.

Workflow 3: Dashboard Grid

Four equal quadrants:

t
n  # Create 4 windows quickly
n
n
n
Ctrl+B =                 # Equalize all splits

Result:

┌─────┬─────┐
│  1  │  2  │
├─────┼─────┤
│  3  │  4  │
└─────┴─────┘

Workflow 4: CI/CD Monitor

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.

Remote Control

Control tiling via CLI for automation:

# Toggle tiling in running session
tuios run-command ToggleTiling

# Enable tiling
tuios send-keys t

# Create window, split, and position
tuios run-command NewWindow "editor"
tuios send-keys "ctrl+b,|"
tuios run-command NewWindow "terminal"

# Equalize splits
tuios send-keys "ctrl+b,="

Implementation Details

Source Code

BSP implementation is in internal/layout/bsp.go:

TileNode struct - Binary tree node with split type and ratio
InsertWindow() - Auto-placement using spiral scheme
RemoveWindow() - Tree cleanup when windows close
ApplyLayout() - Recursive rectangle calculation

Workspace tiling state is managed in internal/app/workspace.go:

TileVisibleWorkspaceWindows() - Tiles only the current workspace
WorkspaceTrees[workspaceNum] - Per-workspace BSP trees
WorkspaceHasCustom[workspaceNum] - Manual split tracking

Automatic Scheme

Default scheme: SchemeSpiral (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)

Split Ratio Storage

Each internal node stores a ratio (default 0.5):

Represents the fraction of space given to left/top child
Range: 0.3 to 0.7 (enforced to prevent unusable layouts)
Adjustable via resize commands

State Persistence

In daemon mode, BSP state is serialized and restored across sessions:

Tree structure
Split ratios
Custom layout flags
Master ratios

See Sessions for persistence details.

Troubleshooting

Windows Not Tiling

Check tiling is enabled

Status bar should show “TILING”. Press t to toggle.

Check workspace

Each workspace has independent tiling state. Try pressing t on the current workspace.

Too many windows

BSP handles any number of windows, but with 10+ windows, individual window size becomes impractical. Consider using multiple workspaces.

Unexpected Layout After Resize

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.

Swap Not Working

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 Not Applied

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.

Workspaces - Each workspace has independent tiling state
Keybindings - Complete keybinding list for tiling
Configuration - Customize tiling behavior
Architecture - Technical details on BSP implementation

Comparison with Other Tiling Algorithms

BSP vs. Grid

Grid Tiling

Fixed positions (1, 2, 3, 4… windows)
Wasted space with odd numbers
Predictable but inflexible

BSP Tiling (TUIOS)

Recursive splits adapt to any number
No wasted space
Full control over layout

BSP vs. Manual Tiling

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.

Get Started

Core Features

Advanced Features

Configuration

Guides

Documentation Index

​Overview

​Key Advantages

Flexible Layout

Custom Sizing

Manual Control

Persistent State

​Enable Tiling

​Auto-Tiling Behavior

​BSP Concepts

​The Split Tree

​Per-Workspace State

​Manual Split Control

​Create Splits

​Rotate Split Direction

​Preselection

​Preselection Commands

​Preselection Workflow

​Window Swapping

​Swap Commands

​Resizing in BSP Mode

​Master Ratio Adjustment

​Height Adjustment

​Edge-Based Resizing

Right Edge (< / >)

Left Edge (, / .)

Bottom Edge ({ / })

Top Edge ([ / ])

​Equalize Splits

​Practical Workflows

​Workflow 1: Development Environment

​Workflow 2: Wide Monitor Layout

​Workflow 3: Dashboard Grid

​Workflow 4: CI/CD Monitor

​Remote Control

​Implementation Details

​Source Code

​Automatic Scheme

​Split Ratio Storage

​State Persistence

​Troubleshooting

​Windows Not Tiling

​Unexpected Layout After Resize

​Swap Not Working

​Preselection Not Applied

​Related Documentation

​Comparison with Other Tiling Algorithms

​BSP vs. Grid

Grid Tiling

BSP Tiling (TUIOS)

​BSP vs. Manual Tiling

Build docs developers (and LLMs) love

Overview

Key Advantages

Enable Tiling

Auto-Tiling Behavior

BSP Concepts

The Split Tree

Per-Workspace State

Manual Split Control

Create Splits

Rotate Split Direction

Preselection

Preselection Commands

Preselection Workflow

Window Swapping

Swap Commands

Resizing in BSP Mode

Master Ratio Adjustment

Height Adjustment

Edge-Based Resizing

Equalize Splits

Practical Workflows

Workflow 1: Development Environment

Workflow 2: Wide Monitor Layout

Workflow 3: Dashboard Grid

Workflow 4: CI/CD Monitor

Remote Control

Implementation Details

Source Code

Automatic Scheme

Split Ratio Storage

State Persistence

Troubleshooting

Windows Not Tiling

Unexpected Layout After Resize

Swap Not Working

Preselection Not Applied

Related Documentation

Comparison with Other Tiling Algorithms

BSP vs. Grid

BSP vs. Manual Tiling