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."
5 -compatibility: "Requires tmux; pairs well with Pi CLI"
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 |
38 -name
="pi_task_$(date +%s)" 40 -notes
="$work/notes.md" 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" 57 -Invariant when requested: exactly one tmux server/session/window; panes are OK.
61 -Use these patterns, adapted to your socket/session names.
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}"; }
69 - tmux -L
"$SOCKET" list-panes -t
"$SESSION:main" \
70 - -F
'#{pane_id} idx=#{pane_index} title=#{pane_title} cmd=#{pane_current_command}' 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 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
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" 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.
101 -TMUX_SKILL_DIR
="$(pwd)" 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
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:
114 -USER_SHELL
="$(basename "${SHELL:-unknown}")" 115 -printf 'shell=%s\nWEZTERM_PANE=%s TERM_PROGRAM=%s\n' \
116 - "$USER_SHELL" "${WEZTERM_PANE-}" "${TERM_PROGRAM-}" 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.
125 - local pane
="$1" root
="$2" cmd
="$3" shell
126 - shell
="$(pane_cmd "$pane")" 128 - nu
|nu.exe
|fish
|pwsh
|powershell.exe
) send_line
"$pane" "cd '$root'; $cmd" ;;
129 - *) send_line
"$pane" "cd '$root' && $cmd" ;;
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.
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.
150 - local pane
="$1" timeout
="${2:-15}" start now
151 - start
="$(date +%s)" 153 - if [ "$(pane_cmd "$pane")" = pi
]; then 156 - [ "$(pane_cmd "$pane")" = pi
] && return 0
159 - [ $((now
- start)) -ge
"$timeout" ] && break 162 - capture
"$pane" -80
>&2 167 - local pane
="$1" text
="$2" 168 - require_cmd
"$pane" pi
|| return 1
169 - tmux -L
"$SOCKET" send-keys -t
"$pane" C-u
171 - send_line
"$pane" "$text" 176 - require_cmd
"$pane" pi
|| return 1
177 - tmux -L
"$SOCKET" send-keys -t
"$pane" C-c
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:
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)" 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:
232 -wezterm cli split-pane --right --cwd
"$ROOT" -- tmux -L
"$SOCKET" attach -t
"$SESSION" 235 -If no terminal can be controlled safely, print the attach command and ask the user to attach before continuing visible testing.