161c633b42
Splits the current pane into evenly-sized grid using wezterm cli split-pane. Supports optional command per pane, dryrun mode, and auto-detects native or Flatpak WezTerm CLI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
90 lines
3.4 KiB
Markdown
90 lines
3.4 KiB
Markdown
# 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
|
||
```
|