dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skillz/terminal-harness/references/wezterm.md

Rendered preview

WezTerm Provider

Use this provider when WEZTERM_PANE identifies the current visible pane and wezterm cli list succeeds. Check installed syntax with wezterm --version and wezterm cli <command> --help. Use pane IDs from CLI output for every operation.

Split and Launch

Pass the program and arguments directly after --.

APP_PANE="$(
  wezterm cli split-pane \
    --pane-id "$WEZTERM_PANE" \
    --right \
    --percent 50 \
    --cwd "$ROOT" \
    -- "$PROGRAM" "${ARGS[@]}"
)"
wezterm cli list --format json

Use --bottom instead of --right for a lower split. If a split is unsuitable, use wezterm cli spawn --new-window --cwd "$ROOT" -- "$PROGRAM" "${ARGS[@]}".

Observe

wezterm cli get-text --pane-id "$APP_PANE"
wezterm cli get-text --pane-id "$APP_PANE" --start-line -200
wezterm cli list --format json

The first command captures the current screen. The second includes recent scrollback.

Wait for a State

Poll until a literal marker appears. The loop returns as soon as the marker shows, a capture failure breaks it, and the seq times sleep product bounds the wait.

out=""
for i in $(seq 60); do
  out=$(wezterm cli get-text --pane-id "$APP_PANE") || break
  printf '%s' "$out" | grep -qF -- "$MARKER" && break
  sleep 5
done
printf '%s' "$out"

Match markers with grep -F so text like [ok] or done. is literal, not a regex. Never park a wait in sleep N; wezterm cli get-text; the bash tool timeout is only a kill ceiling, and pi has no key that ends one tool call without aborting the whole turn.

Input

send-text --pane-id writes to the target pane without activating or focusing its GUI. Use it before desktop-driving for app-level input.

Literal text and Enter:

printf '%s' "$TEXT" | wezterm cli send-text --pane-id "$APP_PANE"
printf '\r' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste

Common app key bytes:

printf '\t' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste      # Tab
printf '\033' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Escape
printf '\033[A' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Up
printf '\033[B' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Down
printf '\033[C' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Right
printf '\033[D' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Left
printf '\003' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Ctrl+C
printf '\017' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Ctrl+O
printf '\025' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Ctrl+U

Send each key separately and capture the resulting state. These bytes exercise the app's terminal input, not WezTerm's GUI keybinding translation. Use desktop-driving only for terminal-host keybinding behavior, mouse/focus behavior, visual evidence, or undocumented key sequences.

wezterm record launches a child and records output events only. It neither attaches to an existing pane nor records input, so use it for replayable evidence, not control.

Inspect and Close

wezterm cli activate-pane --pane-id "$APP_PANE"
wezterm cli kill-pane --pane-id "$APP_PANE"

# WezTerm Provider

Use this provider when `WEZTERM_PANE` identifies the current visible pane and `wezterm cli list` succeeds.
Check installed syntax with `wezterm --version` and `wezterm cli <command> --help`.
Use pane IDs from CLI output for every operation.

## Split and Launch

Pass the program and arguments directly after `--`.

```bash
APP_PANE="$(
  wezterm cli split-pane \
    --pane-id "$WEZTERM_PANE" \
    --right \
    --percent 50 \
    --cwd "$ROOT" \
    -- "$PROGRAM" "${ARGS[@]}"
)"
wezterm cli list --format json
```

Use `--bottom` instead of `--right` for a lower split.
If a split is unsuitable, use `wezterm cli spawn --new-window --cwd "$ROOT" -- "$PROGRAM" "${ARGS[@]}"`.

## Observe

```bash
wezterm cli get-text --pane-id "$APP_PANE"
wezterm cli get-text --pane-id "$APP_PANE" --start-line -200
wezterm cli list --format json
```

The first command captures the current screen.
The second includes recent scrollback.

## Wait for a State

Poll until a literal marker appears.
The loop returns as soon as the marker shows, a capture failure breaks it, and the `seq` times `sleep` product bounds the wait.

```bash
out=""
for i in $(seq 60); do
  out=$(wezterm cli get-text --pane-id "$APP_PANE") || break
  printf '%s' "$out" | grep -qF -- "$MARKER" && break
  sleep 5
done
printf '%s' "$out"
```

Match markers with `grep -F` so text like `[ok]` or `done.` is literal, not a regex.
Never park a wait in `sleep N; wezterm cli get-text`;
the bash tool timeout is only a kill ceiling, and pi has no key that ends one tool call without aborting the whole turn.

## Input

`send-text --pane-id` writes to the target pane without activating or focusing its GUI.
Use it before desktop-driving for app-level input.

Literal text and Enter:

```bash
printf '%s' "$TEXT" | wezterm cli send-text --pane-id "$APP_PANE"
printf '\r' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste
```

Common app key bytes:

```bash
printf '\t' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste      # Tab
printf '\033' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Escape
printf '\033[A' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Up
printf '\033[B' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Down
printf '\033[C' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Right
printf '\033[D' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste  # Left
printf '\003' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Ctrl+C
printf '\017' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Ctrl+O
printf '\025' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste    # Ctrl+U
```

Send each key separately and capture the resulting state.
These bytes exercise the app's terminal input, not WezTerm's GUI keybinding translation.
Use desktop-driving only for terminal-host keybinding behavior, mouse/focus behavior, visual evidence, or undocumented key sequences.

`wezterm record` launches a child and records output events only.
It neither attaches to an existing pane nor records input, so use it for replayable evidence, not control.

## Inspect and Close

```bash
wezterm cli activate-pane --pane-id "$APP_PANE"
wezterm cli kill-pane --pane-id "$APP_PANE"
```