# 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

```bash
# 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
```