small-scripts/specs/split-wezterm.spec.md

split-wezterm — OpenSpec

Purpose

Split the current WezTerm pane into an evenly-sized grid of rows × columns, optionally running a command in each new pane.

Usage

split-wezterm <rows> <cols> [--] [command...]
split-wezterm --help
split-wezterm --dryrun <rows> <cols> [--] [command...]

Arguments

Argument	Required	Description
rows	Yes	Number of rows (1-10)
cols	Yes	Number of columns (1-10)
command...	No	Command to run in each new pane. If omitted, panes open the default shell.

Flags

Flag	Description
--help, -h	Show usage information
--dryrun, -n	Preview the split-pane commands without executing them

Behaviour

1. Validate that rows and cols are integers between 1 and 10
2. Detect the WezTerm CLI binary (wezterm or flatpak run org.wezfurlong.wezterm)
3. Get the current pane ID from $WEZTERM_PANE or fall back to wezterm cli list to find the active pane
4. Create the grid using the following algorithm: a. Create rows first: Split the original pane vertically (rows-1) times. Each split uses --bottom --percent P where P is calculated to produce equal-height rows. The first split takes (rows-1)/rows as the bottom percent, the next takes (rows-2)/(rows-1), etc. b. Collect row pane IDs: The original pane becomes row 0. Each split-pane --bottom returns the new pane ID. c. Create columns: For each row pane, split horizontally (cols-1) times using the same proportional math for equal-width columns. d. Run command: If a command was specified, pass it as the program argument to each split-pane call. The first pane (original) doesn't get split — if a command is specified, use wezterm cli send-text to run it there.
5. Output a summary: "Created {rows}x{cols} grid ({total} panes)"

Proportional splitting math

To split a pane into N equal parts:

• Split i (0-indexed, i=0..N-2): percent = (N - 1 - i) * 100 / (N - i)
• This ensures each resulting section is 1/N of the original.

Example for 3 splits: percent = 66, 50 (producing 33/33/33 split).

Dryrun behaviour

In --dryrun mode, print each wezterm cli split-pane command that would be executed, prefixed with [dryrun]. Do not execute any commands. Still validate inputs and detect the CLI binary.

Example:

[dryrun] wezterm cli split-pane --pane-id 0 --bottom --percent 66
[dryrun] wezterm cli split-pane --pane-id 0 --bottom --percent 50
[dryrun] wezterm cli split-pane --pane-id 0 --horizontal --percent 75
...
[dryrun] Would create 3x4 grid (12 panes)

Edge cases

• 1 1 — No splits needed. Print "Already a single pane, nothing to do." and exit 0.
• 1 N — Only horizontal splits (columns only, no row splits).
• N 1 — Only vertical splits (rows only, no column splits).
• No WezTerm CLI available — exit 1 with error message.
• $WEZTERM_PANE not set and no active pane found — exit 1 with error.
• Non-integer or out-of-range arguments — exit 1 with usage hint.

Examples

# Split into 3 rows x 4 columns
split-wezterm 3 4

# Split into 2x2 grid, each pane running htop
split-wezterm 2 2 -- htop

# Split into 2x3 grid, each running claude with a profile
split-wezterm 2 3 -- claude-with-profiles

# Preview what would happen
split-wezterm --dryrun 3 4

# Single row, 3 columns
split-wezterm 1 3