repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

refactor(pi): unify terminal harness control

e22a6db429d7ab35b33f6ae130db2bc7d6694e10

Oliver Krylow <o.krylow@isp-insoft.de> ·

unsigned

Browse filesCompare with HEAD

Changed files (7)

pi/agent/skills/terminal-harness/SKILL.md

Added
new file mode 100644
1 +---
2 +name: terminal-harness
3 +description: "Use when driving or observing an interactive terminal program, including CLIs, TUIs, nested agents, long-running jobs, and terminal E2E tests."
4 +license: GPLv3
5 +compatibility: "Requires an active tmux or WezTerm control context; tmux also supports detached fallback sessions."
6 +---
8 +# Terminal Harness
10 +Drive an interactive program in a terminal that the agent and user can both observe.
12 +## Choose a Provider
14 +1. Use tmux when `TMUX` and `TMUX_PANE` are set and `tmux` is available.
15 +2. Otherwise use WezTerm when `WEZTERM_PANE` is set and `wezterm cli list` succeeds.
16 +3. Otherwise use a detached tmux session when `tmux` is available, then ask the user to attach before continuing observable work.
17 +4. If none applies, report the missing control context and stop.
19 +Read only the selected provider reference:
21 +- [tmux](references/tmux.md)
22 +- [WezTerm](references/wezterm.md)
24 +A future provider needs one reference file and one selection rule here.
25 +Do not create a generic wrapper or common script.
27 +## Harness Contract
29 +- Create one app pane by splitting the current visible pane.
30 +- Prefer a right split; use a lower split when the app needs more width.
31 +- Use a new window only when splitting is unavailable or leaves insufficient space.
32 +- Add another pane only when the tested workflow requires a concurrent product process.
33 +- Keep notes and orchestration outside product panes.
34 +- Launch the program in its working directory through the provider, not by typing setup commands into the pane.
35 +- Record the provider and stable pane ID immediately.
37 +## Drive the App
39 +1. Observe an app-specific ready state before sending input.
40 +2. Send literal text and control keys as separate actions.
41 +3. After each action, capture the current viewport and wait for a visible state change.
42 +4. Poll observable state with a short bound; never use a blind sleep as control flow.
43 +5. Treat process names as hints, not proof that the app is ready or idle.
44 +6. Use the agent shell for setup, file inspection, and independent verification.
46 +Interrupts are explicit test actions.
47 +Never send `C-c` as generic input clearing.
48 +If input merges, reaches the wrong process, or cannot be attributed, mark that pane polluted and stop using its later output as evidence.
50 +Text capture does not prove colors, layout, animation, cursor behavior, or visual stability.
51 +When those matter, activate the app pane and use an available screenshot or desktop-driving skill.
53 +## Evidence and Lifecycle
55 +- Capture the command, cwd, provider, pane ID, relevant viewport states, and resulting artifacts.
56 +- Distinguish product failures from harness failures.
57 +- Verify app claims through files, processes, browser state, or other external effects.
58 +- Leave the app pane available for inspection unless the user requested cleanup.
59 +- Report the pane ID and provider-specific focus, inspection, and cleanup commands.

pi/agent/skills/terminal-harness/references/tmux.md

Added
new file mode 100644
1 +# tmux Provider
3 +Use this provider inside an active tmux client.
4 +A detached session is the fallback when tmux exists but no controllable terminal multiplexer is active.
6 +Check installed syntax with `tmux -V` and `man tmux`.
7 +Use pane IDs such as `%12`, never pane indexes.
9 +## Split and Launch
11 +`COMMAND` must be one correctly shell-quoted command string.
13 +```bash
14 +APP_PANE="$(tmux split-window -h -P -F '#{pane_id}' -t "$TMUX_PANE" -c "$ROOT" "$COMMAND")"
15 +tmux display-message -p -t "$APP_PANE" '#{pane_id} cmd=#{pane_current_command}'
16 +```
18 +Use `-v` instead of `-h` for a lower split.
19 +Keep `APP_PANE` for every later operation.
21 +For a detached fallback:
23 +```bash
24 +SOCKET="terminal-harness-$(date +%s)"
25 +APP_PANE="$(tmux -L "$SOCKET" new-session -d -P -F '#{pane_id}' -s live -n app -c "$ROOT" "$COMMAND")"
26 +tmux -L "$SOCKET" attach -t live
27 +tmux -L "$SOCKET" kill-server
28 +```
30 +Prefix all detached-session operations with `tmux -L "$SOCKET"`.
32 +## Observe
34 +```bash
35 +tmux display-message -p -t "$APP_PANE" '#{pane_id} cmd=#{pane_current_command}'
36 +tmux capture-pane -p -J -t "$APP_PANE" -S -200
37 +```
39 +Alternate-screen TUIs may expose only the current viewport.
41 +## Input
43 +Literal text and Enter:
45 +```bash
46 +printf '%s' "$TEXT" | tmux load-buffer -
47 +tmux paste-buffer -d -t "$APP_PANE"
48 +tmux send-keys -t "$APP_PANE" Enter
49 +```
51 +Control keys:
53 +```bash
54 +tmux send-keys -t "$APP_PANE" C-c
55 +tmux send-keys -t "$APP_PANE" C-u
56 +```
58 +## Inspect and Close
60 +```bash
61 +tmux select-pane -t "$APP_PANE"
62 +tmux kill-pane -t "$APP_PANE"
63 +```

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

Added
new file mode 100644
1 +# WezTerm Provider
3 +Use this provider when `WEZTERM_PANE` identifies the current visible pane and `wezterm cli list` succeeds.
4 +Check installed syntax with `wezterm --version` and `wezterm cli <command> --help`.
5 +Use pane IDs from CLI output for every operation.
7 +## Split and Launch
9 +Pass the program and arguments directly after `--`.
11 +```bash
12 +APP_PANE="$(
13 + wezterm cli split-pane \
14 + --pane-id "$WEZTERM_PANE" \
15 + --right \
16 + --percent 50 \
17 + --cwd "$ROOT" \
18 + -- "$PROGRAM" "${ARGS[@]}"
19 +)"
20 +wezterm cli list --format json
21 +```
23 +Use `--bottom` instead of `--right` for a lower split.
24 +If a split is unsuitable, use `wezterm cli spawn --new-window --cwd "$ROOT" -- "$PROGRAM" "${ARGS[@]}"`.
26 +## Observe
28 +```bash
29 +wezterm cli get-text --pane-id "$APP_PANE"
30 +wezterm cli get-text --pane-id "$APP_PANE" --start-line -200
31 +wezterm cli list --format json
32 +```
34 +The first command captures the current screen.
35 +The second includes recent scrollback.
37 +## Input
39 +`send-text --pane-id` writes to the target pane without activating or focusing its GUI.
40 +Use it before desktop-driving for app-level input.
42 +Literal text and Enter:
44 +```bash
45 +printf '%s' "$TEXT" | wezterm cli send-text --pane-id "$APP_PANE"
46 +printf '\r' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste
47 +```
49 +Common app key bytes:
51 +```bash
52 +printf '\t' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Tab
53 +printf '\033' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Escape
54 +printf '\033[A' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Up
55 +printf '\033[B' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Down
56 +printf '\033[C' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Right
57 +printf '\033[D' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Left
58 +printf '\003' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Ctrl+C
59 +printf '\017' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Ctrl+O
60 +printf '\025' | wezterm cli send-text --pane-id "$APP_PANE" --no-paste # Ctrl+U
61 +```
63 +Send each key separately and capture the resulting state.
64 +These bytes exercise the app's terminal input, not WezTerm's GUI keybinding translation.
65 +Use desktop-driving only for terminal-host keybinding behavior, mouse/focus behavior, visual evidence, or undocumented key sequences.
67 +`wezterm record` launches a child and records output events only.
68 +It neither attaches to an existing pane nor records input, so use it for replayable evidence, not control.
70 +## Inspect and Close
72 +```bash
73 +wezterm cli activate-pane --pane-id "$APP_PANE"
74 +wezterm cli kill-pane --pane-id "$APP_PANE"
75 +```

pi/agent/skills/tmux/SKILL.md

Deleted
deleted file mode 100644
1 ----
2 -name: tmux
3 -description: "Use when a task needs driving or observing interactive CLIs/TUIs/agents, long-running jobs, servers/logs/watchers, browser/terminal E2E smoke tests, queued/busy-state input, persistent SSH sessions, or multi-pane harnesses."
4 -license: GPLv3
5 -compatibility: "Requires tmux; pairs well with Pi CLI"
6 ----
8 -# tmux Agent Harness
10 -Use tmux as a real terminal harness: spawn processes, send keys, capture panes, preserve proof. Prefer tmux for interactive CLIs/TUIs, nested Pi, long-running jobs, logs/watchers, multi-process repros, and live smoke tests.
12 -## Non-Negotiable Protocol
14 -1. **Use pane IDs (`%12`), not pane indexes (`main.3`).** Pane indexes change after splits. Capture pane IDs with `split-window -P -F '#{pane_id}'` and keep a pane ledger in notes.
15 -2. **Refresh pane map after every split/kill/relaunch.** Run `tmux list-panes -F '#{pane_id} #{pane_index} #{pane_title} #{pane_current_command}'`.
16 -3. **Classify pane state before sending input.** Shell, launching, app idle, app busy, app dead require different actions.
17 -4. **Never hide `C-c` inside generic send helpers.** Interrupts are explicit actions only.
18 -5. **Never send app commands unless the target pane is running that app.** If `pane_current_command != pi`, `/tune` goes to the shell, not Pi.
19 -6. **Wait for readiness; do not sleep-and-hope.** Launch command accepted ≠ app ready.
20 -7. **If input merges, command goes to wrong shell, or pane is polluted: stop using that pane for product evidence.** Mark notes as polluted, open a clean pane, remap IDs.
21 -8. **Use the agent shell for orchestration.** Send only simple launch lines and test inputs into panes; do complex setup via tools/scripts outside tmux.
22 -9. **Keep sessions alive for inspection unless user asked cleanup.** Print attach/kill commands.
24 -## Pane State Machine
26 -| State | Evidence | Allowed action |
27 -| --------- | --------------------------------------------------------------- | ---------------------------------------------------- |
28 -| shell | `pane_current_command` is `bash`, `nu`, `fish`, `zsh`, `pwsh` | shell commands only |
29 -| launching | launch just sent, command maybe still shell | wait/probe only |
30 -| app idle | `pane_current_command` is app (`pi`, `vim`, etc.) and UI stable | app inputs OK |
31 -| app busy | spinner/tool output/running child | wait, observe, or explicit interrupt if testing stop |
32 -| app dead | app process gone/back to shell | relaunch or finish; no app commands |
34 -## Minimal Harness
36 -```bash
37 -set -euo pipefail
38 -name="pi_task_$(date +%s)"
39 -work="/tmp/$name"
40 -notes="$work/notes.md"
41 -mkdir -p "$work"
43 -tmux -L "$name" new-session -d -s live -n main -c "$work"
44 -pi_pane="$(tmux -L "$name" display-message -p -t live:main '#{pane_id}')"
45 -notes_pane="$(tmux -L "$name" split-window -h -P -F '#{pane_id}' -t "$pi_pane" -c "$work")"
46 -obs_pane="$(tmux -L "$name" split-window -v -P -F '#{pane_id}' -t "$notes_pane" -c "$work")"
48 -tmux -L "$name" select-pane -t "$pi_pane" -T pi
49 -tmux -L "$name" select-pane -t "$notes_pane" -T notes
50 -tmux -L "$name" select-pane -t "$obs_pane" -T observer
52 -tmux -L "$name" list-panes -F '#{pane_id} #{pane_index} #{pane_title} #{pane_current_command}' | tee -a "$notes"
53 -echo "attach: tmux -L $name attach -t live" | tee -a "$notes"
54 -echo "kill: tmux -L $name kill-server" | tee -a "$notes"
55 -```
57 -Invariant when requested: exactly one tmux server/session/window; panes are OK.
59 -## Required Helpers
61 -Use these patterns, adapted to your socket/session names.
63 -```bash
64 -pane_cmd() { tmux -L "$SOCKET" display-message -p -t "$1" '#{pane_current_command}'; }
65 -pane_pid() { tmux -L "$SOCKET" display-message -p -t "$1" '#{pane_pid}'; }
66 -capture() { tmux -L "$SOCKET" capture-pane -t "$1" -p -S "${2:--120}"; }
68 -pane_map() {
69 - tmux -L "$SOCKET" list-panes -t "$SESSION:main" \
70 - -F '#{pane_id} idx=#{pane_index} title=#{pane_title} cmd=#{pane_current_command}'
73 -require_cmd() {
74 - local pane="$1" expected="$2" actual
75 - actual="$(pane_cmd "$pane")"
76 - [ "$actual" = "$expected" ] || {
77 - echo "WRONG_PANE_STATE pane=$pane expected=$expected actual=$actual" >&2
78 - pane_map >&2
79 - return 1
80 - }
83 -send_line() {
84 - local pane="$1" text="$2"
85 - printf '%s' "$text" | tmux -L "$SOCKET" load-buffer -
86 - tmux -L "$SOCKET" paste-buffer -t "$pane"
87 - tmux -L "$SOCKET" send-keys -t "$pane" Enter
90 -wait_for_text() {
91 - local pane="$1" pattern="$2" timeout="${3:-15}"
92 - "$TMUX_SKILL_DIR/scripts/wait-for-text.sh" -L "$SOCKET" -t "$pane" -p "$pattern" -T "$timeout"
94 -```
96 -## Skill Scripts
98 -Set `TMUX_SKILL_DIR` to this skill directory when using bundled helpers. Resolve it relative to this `SKILL.md`; do not hardcode a home path.
100 -```bash
101 -TMUX_SKILL_DIR="$(pwd)" # when cwd is this skill directory
102 -"$TMUX_SKILL_DIR/scripts/find-sessions.sh" -L "$SOCKET"
103 -"$TMUX_SKILL_DIR/scripts/wait-for-text.sh" -L "$SOCKET" -t "$pane" -p '^>>>' -T 15
104 -```
106 -- `find-sessions.sh` lists sessions and pane IDs; prefer `%pane_id` from its output.
107 -- `wait-for-text.sh` polls captured pane text with regex/fixed-string matching; use it instead of blind sleeps.
109 -## Shell-Aware Launch
111 -Probe the user's shell/terminal before pane work:
113 -```bash
114 -USER_SHELL="$(basename "${SHELL:-unknown}")"
115 -printf 'shell=%s\nWEZTERM_PANE=%s TERM_PROGRAM=%s\n' \
116 - "$USER_SHELL" "${WEZTERM_PANE-}" "${TERM_PROGRAM-}"
117 -```
119 -For pane launches, keep commands simple. Nushell/Fish/PowerShell use `;`, not Bash `&&`.
121 -For Python REPLs, launch with `PYTHON_BASIC_REPL=1 python3 -q`. Python 3.13+ defaults to PyREPL, which emits terminal-control behavior that confuses `send-keys`/`capture-pane`; `PYTHON_BASIC_REPL=1` forces the old plain prompt.
123 -```bash
124 -launch_pi() {
125 - local pane="$1" root="$2" cmd="$3" shell
126 - shell="$(pane_cmd "$pane")"
127 - case "$shell" in
128 - nu|nu.exe|fish|pwsh|powershell.exe) send_line "$pane" "cd '$root'; $cmd" ;;
129 - *) send_line "$pane" "cd '$root' && $cmd" ;;
130 - esac
132 -```
134 -## Pi-In-tmux Safe Pattern
136 -Pi uses an alternate screen and an editor; `capture-pane` may be incomplete. Verify via panes **and** artifacts/session JSONL.
138 -### Wait Budget
140 -Default to short, condition-based waits. Long timeouts hide harness bugs and delay work.
142 -- Readiness/startup: 15s default.
143 -- UI settle after keypress: 0.2–1s.
144 -- No-progress checkpoint: 10s; capture pane/artifacts and decide.
145 -- Any wait >30s requires a recorded reason and progress signal.
146 -- Never use `sleep N` as control flow; poll a state/artifact/process.
148 -```bash
149 -wait_for_pi() {
150 - local pane="$1" timeout="${2:-15}" start now
151 - start="$(date +%s)"
152 - while :; do
153 - if [ "$(pane_cmd "$pane")" = pi ]; then
154 - # Require stability across two polls; pane text may be sparse in alt screen.
155 - sleep 0.25
156 - [ "$(pane_cmd "$pane")" = pi ] && return 0
157 - fi
158 - now="$(date +%s)"
159 - [ $((now - start)) -ge "$timeout" ] && break
160 - sleep 0.5
161 - done
162 - capture "$pane" -80 >&2
163 - return 1
166 -pi_submit() {
167 - local pane="$1" text="$2"
168 - require_cmd "$pane" pi || return 1
169 - tmux -L "$SOCKET" send-keys -t "$pane" C-u
170 - sleep 0.2
171 - send_line "$pane" "$text"
174 -pi_interrupt() {
175 - local pane="$1"
176 - require_cmd "$pane" pi || return 1
177 - tmux -L "$SOCKET" send-keys -t "$pane" C-c
179 -```
181 -Rules for Pi:
183 -- Do not send `C-c` before every prompt. It can kill a fresh/launching Pi.
184 -- If Pi exits, the pane returns to shell; `/command` becomes a shell command.
185 -- If a command appears concatenated with the launch line, mark pane polluted and stop using it for evidence.
186 -- If TUI output is opaque, use file artifacts, Pi session JSONL, process inspection, or direct SDK tests.
188 -## Stopping Busy Apps
190 -Do not mash keys. Use a bounded, recorded stop sequence:
192 -1. If testing product stop UX, send the documented stop input once.
193 -2. Wait a bounded time and capture evidence.
194 -3. If still busy after 10s without visible progress, record UX failure.
195 -4. Find child process and signal directly:
197 -```bash
198 -root_pid="$(pane_pid "$pane")"
199 -pgrep -P "$root_pid" -a
200 -kill -INT "$(pgrep -P "$root_pid" -f '^/usr/bin/pi' | head -1)"
201 -```
203 -Record residual files/locks after forced stop.
205 -## Evidence Discipline
207 -- Keep notes in a temp markdown file from the start.
208 -- Record command lines, pane IDs, model/provider when visible, cwd, shell, socket/session/window, and artifact paths.
209 -- Use unique markers for assertions.
210 -- Treat nested agents' claims as untrusted; verify externally.
211 -- Mark harness mistakes immediately; do not mix polluted evidence with product findings.
213 -## Common Anti-Patterns
215 -- `SESSION:main.3` after dynamic splits → use `%pane_id`.
216 -- Generic helper sends `C-c` → split submit vs interrupt helpers.
217 -- Slash command sent while pane is `nu`/`bash` → check `pane_current_command` first.
218 -- Launch Pi then immediately paste prompt → wait for `pi` readiness.
219 -- `sleep 5` as readiness → poll state/artifacts.
220 -- Huge defensive timeouts → small budget + progress checkpoints + explicit escalation.
221 -- Capture old scrollback as current output → use markers/timestamps and recent captures.
222 -- Continue from command-concatenated pane → declare polluted and open clean pane.
223 -- Complex Bash pasted into Nushell/Fish/PowerShell → orchestrate outside pane or use shell-aware syntax.
224 -- Runaway nested model session → bounded stop plan + direct child signal.
225 -- Killing tmux server without user consent → leave attach/kill commands.
227 -## Visible Terminal / WezTerm
229 -Use tmux for harness logic. If user asks for observable work and WezTerm is available, load the `wezterm` skill and attach visually:
231 -```bash
232 -wezterm cli split-pane --right --cwd "$ROOT" -- tmux -L "$SOCKET" attach -t "$SESSION"
233 -```
235 -If no terminal can be controlled safely, print the attach command and ask the user to attach before continuing visible testing.

pi/agent/skills/tmux/scripts/find-sessions.sh

Deleted
deleted file mode 100755
1 -#!/usr/bin/env bash
2 -set -euo pipefail
4 -usage() {
5 - cat <<'USAGE'
6 -Usage: find-sessions.sh [-L socket-name|-S socket-path|--all] [-q pattern]
8 -List tmux sessions with panes.
10 -Options:
11 - -L, --socket tmux socket name
12 - -S, --socket-path tmux socket path
13 - -A, --all scan /tmp/tmux-$UID and PI_TMUX_SOCKET_DIR
14 - -q, --query case-insensitive session-name filter
15 - -h, --help show help
16 -USAGE
17 -}
19 -socket_name=""
20 -socket_path=""
21 -query=""
22 -scan_all=false
23 -socket_dir="${PI_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/pi-tmux-sockets}"
25 -while [[ $# -gt 0 ]]; do
26 - case "$1" in
27 - -L|--socket) socket_name="${2-}"; shift 2 ;;
28 - -S|--socket-path) socket_path="${2-}"; shift 2 ;;
29 - -A|--all) scan_all=true; shift ;;
30 - -q|--query) query="${2-}"; shift 2 ;;
31 - -h|--help) usage; exit 0 ;;
32 - *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
33 - esac
34 -done
36 -[[ -z "$socket_name" || -z "$socket_path" ]] || { echo "use -L or -S, not both" >&2; exit 1; }
37 -[[ "$scan_all" == false || ( -z "$socket_name" && -z "$socket_path" ) ]] || { echo "--all cannot combine with -L/-S" >&2; exit 1; }
38 -command -v tmux >/dev/null || { echo "tmux not found" >&2; exit 1; }
40 -list_one() {
41 - local label="$1"; shift
42 - local tmux_cmd=(tmux "$@")
43 - local sessions panes
45 - sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}|#{session_attached}|#{session_created_string}' 2>/dev/null || true)"
46 - [[ -n "$sessions" ]] || return 1
47 - [[ -z "$query" ]] || sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
48 - [[ -n "$sessions" ]] || return 0
50 - echo "Sessions on $label:"
51 - while IFS='|' read -r name attached created; do
52 - [[ -n "$name" ]] || continue
53 - [[ "$attached" == 1 ]] && attached_label=attached || attached_label=detached
54 - printf ' %s (%s, %s)\n' "$name" "$attached_label" "$created"
55 - panes="$("${tmux_cmd[@]}" list-panes -t "$name" -F ' #{pane_id} idx=#{pane_index} title=#{pane_title} cmd=#{pane_current_command}' 2>/dev/null || true)"
56 - printf '%s\n' "$panes"
57 - done <<< "$sessions"
58 -}
60 -if [[ "$scan_all" == true ]]; then
61 - paths=()
62 - [[ -d "$socket_dir" ]] && while IFS= read -r -d '' path; do paths+=("$path"); done < <(find "$socket_dir" -maxdepth 1 -type s -print0 2>/dev/null)
63 - default_dir="/tmp/tmux-$(id -u)"
64 - [[ -d "$default_dir" ]] && while IFS= read -r -d '' path; do paths+=("$path"); done < <(find "$default_dir" -maxdepth 1 -type s -print0 2>/dev/null)
65 - [[ ${#paths[@]} -gt 0 ]] || { echo "No tmux sockets found" >&2; exit 1; }
67 - found=false
68 - for path in "${paths[@]}"; do
69 - if list_one "socket path '$path'" -S "$path"; then found=true; fi
70 - done
71 - [[ "$found" == true ]] || { echo "No sessions found" >&2; exit 1; }
72 - exit 0
73 -fi
75 -tmux_args=()
76 -label="default socket"
77 -if [[ -n "$socket_name" ]]; then
78 - tmux_args=(-L "$socket_name")
79 - label="socket name '$socket_name'"
80 -elif [[ -n "$socket_path" ]]; then
81 - tmux_args=(-S "$socket_path")
82 - label="socket path '$socket_path'"
83 -fi
85 -list_one "$label" "${tmux_args[@]}" || { echo "No sessions found on $label" >&2; exit 1; }

pi/agent/skills/tmux/scripts/wait-for-text.sh

Deleted
deleted file mode 100755
1 -#!/usr/bin/env bash
2 -set -euo pipefail
4 -usage() {
5 - cat <<'USAGE'
6 -Usage: wait-for-text.sh [-L socket-name|-S socket-path] -t target -p pattern [options]
8 -Poll a tmux pane until text appears.
10 -Options:
11 - -L, --socket tmux socket name
12 - -S, --socket-path tmux socket path
13 - -t, --target pane target; prefer %pane_id
14 - -p, --pattern regex pattern; required
15 - -F, --fixed fixed string match
16 - -T, --timeout seconds; default 15
17 - -i, --interval poll interval seconds; default 0.5
18 - -l, --lines history lines; default 1000
19 - -h, --help show help
20 -USAGE
21 -}
23 -socket_name=""
24 -socket_path=""
25 -target=""
26 -pattern=""
27 -grep_flag="-E"
28 -timeout=15
29 -interval=0.5
30 -lines=1000
32 -while [[ $# -gt 0 ]]; do
33 - case "$1" in
34 - -L|--socket) socket_name="${2-}"; shift 2 ;;
35 - -S|--socket-path) socket_path="${2-}"; shift 2 ;;
36 - -t|--target) target="${2-}"; shift 2 ;;
37 - -p|--pattern) pattern="${2-}"; shift 2 ;;
38 - -F|--fixed) grep_flag="-F"; shift ;;
39 - -T|--timeout) timeout="${2-}"; shift 2 ;;
40 - -i|--interval) interval="${2-}"; shift 2 ;;
41 - -l|--lines) lines="${2-}"; shift 2 ;;
42 - -h|--help) usage; exit 0 ;;
43 - *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
44 - esac
45 -done
47 -[[ -n "$target" && -n "$pattern" ]] || { echo "target and pattern required" >&2; usage; exit 1; }
48 -[[ "$timeout" =~ ^[0-9]+$ ]] || { echo "timeout must be integer seconds" >&2; exit 1; }
49 -[[ "$lines" =~ ^[0-9]+$ ]] || { echo "lines must be integer" >&2; exit 1; }
50 -[[ -z "$socket_name" || -z "$socket_path" ]] || { echo "use -L or -S, not both" >&2; exit 1; }
51 -command -v tmux >/dev/null || { echo "tmux not found" >&2; exit 1; }
53 -tmux_cmd=(tmux)
54 -[[ -n "$socket_name" ]] && tmux_cmd+=(-L "$socket_name")
55 -[[ -n "$socket_path" ]] && tmux_cmd+=(-S "$socket_path")
57 -deadline=$(($(date +%s) + timeout))
58 -pane_text=""
60 -while :; do
61 - pane_text="$("${tmux_cmd[@]}" capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
62 - if printf '%s\n' "$pane_text" | grep "$grep_flag" -- "$pattern" >/dev/null 2>&1; then
63 - exit 0
64 - fi
66 - if (( $(date +%s) >= deadline )); then
67 - echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
68 - echo "Last ${lines} lines from $target:" >&2
69 - printf '%s\n' "$pane_text" >&2
70 - exit 1
71 - fi
73 - sleep "$interval"
74 -done

pi/agent/skills/wezterm/SKILL.md

Modified
2 2 name: wezterm
3 -description: WezTerm terminal emulator configuration — Lua config, panes, tabs, multiplexer (SSH/WSL domains), key bindings, CLI, and appearance. Use when configuring WezTerm, writing ~/.wezterm.lua, building key bindings, using mux workspaces, or automating the CLI.
3 +description: "WezTerm terminal emulator configuration: Lua config, panes, tabs, domains, key bindings, and appearance. Use for configuring WezTerm itself; use terminal-harness to drive interactive terminal programs."
6 6 # WezTerm Skill
452 452 ## CLI Reference
454 +Use `terminal-harness` for pane control, app input, and screen capture.
455 +This section covers configuration-adjacent commands only.
454 457 ```bash
455 458 # Launch GUI
456 459 wezterm start
464 467 # Connect to domain
465 468 wezterm connect domain-name
467 -# Pane management
468 -wezterm cli split-pane --right -- /bin/bash
469 -wezterm cli split-pane --down --weight 0.3 -- bash -c 'top'
470 -wezterm cli list # list panes/windows/tabs
471 -wezterm cli activate-pane-direction Left
472 -wezterm cli activate-pane 2
473 -wezterm cli zoom-pane
475 -# Send text
476 -wezterm cli send-text --pane-id 1 "echo hello\n"
478 -# Read text
479 -wezterm cli get-text --pane-id 1 --start-cell 0,0 --end-cell 100,50
481 470 # Titles
482 471 wezterm cli set-tab-title --pane-id 1 "My Tab"
483 472 wezterm cli set-window-title --window-id 0 "My Window"
484 473 wezterm cli rename-workspace --name main
486 -# Status
487 -wezterm cli list --format json
489 475 # Utilities
490 476 wezterm show-keys --help # key sequence explorer
491 477 wezterm ls-fonts # list available fonts