repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(tmux): harden harness guidance

b7bfd5dee67f4a53f149461fa3a553a5d15f6dfe

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

skills/tmux/SKILL.md

Modified
2 2 name: tmux
3 -description: "Use tmux as an agent harness for real terminal workflows. Load when a task needs driving or inspecting interactive CLIs/TUIs/agents, long-running jobs, servers/logs/watchers, UI screenshots/pane captures, queued/busy-state input, repro sandboxes, SSH-persistent sessions, or terminal E2E smoke tests—even when tmux is not named. Do not use for pure deterministic logic tests with structured APIs."
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 4 license: GPLv3
5 5 compatibility: "Requires tmux; pairs well with Pi CLI"
8 8 # tmux Agent Harness
10 -Use tmux when the task benefits from a real terminal running independently while
11 -you inspect/control it from outside.
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.
13 -Core idea:
14 -**spawn process → send real keys → poll pane/artifacts → preserve proof**.
12 +## Non-Negotiable Protocol
16 -Default mode:
17 -detached/background tmux session.
18 -The user will not see it unless they attach or the agent opens/prints an attach
19 -command.
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.
21 -## When To Reach For This
24 +## Pane State Machine
23 -Use tmux for:
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 |
25 -- Interactive CLI/TUI testing:
26 - Pi, editors, REPLs, installers, prompts.
27 -- Agent-in-agent workflows:
28 - launch `pi` in a pane, steer it, inspect results.
29 -- Long jobs:
30 - model calls, builds, servers, watchers, migrations.
31 -- UI verification:
32 - status bars, spinners, wrapping, terminal dimensions.
33 -- Timing bugs:
34 - input while busy/idle/paused/waiting.
35 -- Multi-process work:
36 - app + logs + watcher + nested agent.
37 -- Remote resilience:
38 - keep work alive across SSH disconnects.
39 -- Repro sandboxes:
40 - isolated cwd/config/session dirs, exact transcript.
42 -Do not use tmux for:
44 -- Pure deterministic fns.
45 -- Fast unit checks with structured output.
46 -- Secret-heavy workflows where pane scrollback leaks creds.
47 -- Large regression suites needing strict determinism.
49 -## Session + Visibility Policy
51 -- Create dedicated sessions by default:
52 - `pi_<task>_<shortid>`.
53 -- Do not use the user's active/existing session unless explicitly asked.
54 -- Do not send keys to an existing pane unless the user names that session/pane.
55 -- Kill/reuse only sessions owned by this run and matching your exact name.
56 -- For visible work, print `tmux attach -t "$name"` or open a new terminal tab if
57 - the user asked for visibility.
58 -- For debugging, keep session alive and print attach/workdir paths.
60 -## Default Harness
34 +## Minimal Harness
62 36 ```bash
63 37 set -euo pipefail
65 -id=$(date +%s)
66 -name="pi_task_$id"
38 +name="pi_task_$(date +%s)"
67 39 work="/tmp/$name"
69 -rm -rf "$work"
40 +notes="$work/notes.md"
70 41 mkdir -p "$work"
71 -tmux kill-session -t "$name" 2>/dev/null || true
73 -tmux new-session -d -s "$name" -x 120 -y 40 "cd '$work' && pi"
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")"
75 -# readiness/pane probe
76 -tmux capture-pane -t "$name:0.0" -p -S -80
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
78 -echo "attach: tmux attach -t $name"
79 -echo "workdir: $work"
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"
82 -Keep dimensions fixed.
83 -Capture enough history.
84 -Prefer stable markers over whole-screen assertions.
85 -Target panes explicitly (`$name:0.0`) when ambiguity or rapid session changes
86 -are possible.
57 +Invariant when requested: exactly one tmux server/session/window; panes are OK.
88 -## Send Input Safely
59 +## Required Helpers
61 +Use these patterns, adapted to your socket/session names.
90 63 ```bash
91 -send() {
92 - tmux set-buffer -t "$name" "$1"
93 - tmux paste-buffer -t "$name"
94 - tmux send-keys -t "$name" Enter
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}'
97 -pane() {
98 - tmux capture-pane -t "$name:0.0" -p -S "${1:--200}"
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 + }
101 -wait_for() {
102 - local needle="$1"
103 - for i in {1..60}; do
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
89 +```
91 +## Shell-Aware Launch
93 +Probe the user's shell/terminal before pane work:
95 +```bash
96 +USER_SHELL="$(basename "${SHELL:-unknown}")"
97 +printf 'shell=%s\nWEZTERM_PANE=%s TERM_PROGRAM=%s\n' \
98 + "$USER_SHELL" "${WEZTERM_PANE-}" "${TERM_PROGRAM-}"
99 +```
101 +For pane launches, keep commands simple. Nushell/Fish/PowerShell use `;`, not Bash `&&`.
103 +```bash
104 +launch_pi() {
105 + local pane="$1" root="$2" cmd="$3" shell
106 + shell="$(pane_cmd "$pane")"
107 + case "$shell" in
108 + nu|nu.exe|fish|pwsh|powershell.exe) send_line "$pane" "cd '$root'; $cmd" ;;
109 + *) send_line "$pane" "cd '$root' && $cmd" ;;
110 + esac
112 +```
114 +## Pi-In-tmux Safe Pattern
116 +Pi uses an alternate screen and an editor; `capture-pane` may be incomplete. Verify via panes **and** artifacts/session JSONL.
118 +```bash
119 +wait_for_pi() {
120 + local pane="$1"
121 + for _ in {1..60}; do
122 + [ "$(pane_cmd "$pane")" = pi ] || { sleep 1; continue; }
123 + # Require stability across two polls; pane text may be sparse in alt screen.
104 124 sleep 1
105 - pane -300 | grep -q "$needle" && return 0
125 + [ "$(pane_cmd "$pane")" = pi ] && return 0
107 - pane -300 >&2
127 + capture "$pane" -80 >&2
108 128 return 1
110 -```
112 -Special keys:
114 -```bash
115 -tmux send-keys -t "$name" C-c
116 -tmux send-keys -t "$name" Escape
117 -tmux send-keys -t "$name" Tab
118 -```
120 -## Short-lived Interactive Programs
122 -If the program exits immediately after success, tmux may destroy the pane before
123 -you capture proof.
124 -Keep it alive deliberately:
126 -```bash
127 -tmux new-session -d -s "$name" -x 120 -y 24 \
128 - "cd '$work' && ./cli_under_test; echo __SESSION_ENDED__; exec bash"
129 -```
131 -Avoid piping interactive programs through `tee`; a pipe can break TTY input.
132 -Prefer `capture-pane` for terminal proof and app-owned log files for structured
133 -proof.
135 -## Pi-In-tmux Pattern
137 -Use nested Pi when you need a real agent session, not just `pi -p` output.
139 -Pi's TUI has autocomplete/editor state.
140 -Scripted input must be defensive:
142 -```bash
143 -# Discover exact pane; don't assume :0.0 (tmux may allocate window/pane index 1).
144 -tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_current_command}'
146 -target="$name:1.1" # set from list-panes output
148 -pi_send() {
149 - tmux send-keys -t "$target" C-u # clear editor/autocomplete leftovers
150 - printf '%s' "$1" | tmux load-buffer - # exact paste, no shell quoting surprises
151 - tmux paste-buffer -t "$target"
152 - tmux send-keys -t "$target" Enter
131 +pi_submit() {
132 + local pane="$1" text="$2"
133 + require_cmd "$pane" pi || return 1
134 + tmux -L "$SOCKET" send-keys -t "$pane" C-u
135 + sleep 0.2
136 + send_line "$pane" "$text"
155 -pi_send '/my-command arg'
139 +pi_interrupt() {
140 + local pane="$1"
141 + require_cmd "$pane" pi || return 1
142 + tmux -L "$SOCKET" send-keys -t "$pane" C-c
158 -If autocomplete opens, submitted text remains in editor, or command text merges
159 -with previous text:
160 -send `C-u`, retry.
161 -For prototype extensions, avoid command argument completions unless completion
162 -behavior is under test.
146 +Rules for Pi:
147 +- Do not send `C-c` before every prompt. It can kill a fresh/launching Pi.
148 +- If Pi exits, the pane returns to shell; `/command` becomes a shell command.
149 +- If a command appears concatenated with the launch line, mark pane polluted and stop using it for evidence.
150 +- If TUI output is opaque, use file artifacts, Pi session JSONL, process inspection, or direct SDK tests.
152 +## Stopping Busy Apps
154 +Do not mash keys. Use a bounded, recorded stop sequence:
156 +1. If testing product stop UX, send the documented stop input once.
157 +2. Wait a bounded time and capture evidence.
158 +3. If still busy, record UX failure.
159 +4. Find child process and signal directly:
164 161 ```bash
165 -name=pi_nested
166 -work=/tmp/$name
167 -agent_dir="$work/.pi-agent"
169 -rm -rf "$work"
170 -mkdir -p "$work" "$agent_dir"
171 -tmux kill-session -t "$name" 2>/dev/null || true
173 -tmux new-session -d -s "$name" -x 140 -y 42 \
174 - "cd '$work' && PI_CODING_AGENT_DIR='$agent_dir' pi"
176 -send 'Create proof.txt containing EXACT_MARKER_9f3a, then print DONE_MARKER_9f3a.'
177 -wait_for 'DONE_MARKER_9f3a'
178 -find "$work" -maxdepth 3 -type f -print
179 -cat "$work/proof.txt"
162 +root_pid="$(pane_pid "$pane")"
163 +pgrep -P "$root_pid" -a
164 +kill -INT "$(pgrep -P "$root_pid" -f '^/usr/bin/pi' | head -1)"
182 -Use unique markers per run.
183 -Isolate `PI_CODING_AGENT_DIR` so global sessions, extensions, auth, prompts, and
184 -logs do not contaminate proof.
167 +Record residual files/locks after forced stop.
186 -## WezTerm + tmux
169 +## Evidence Discipline
188 -Use tmux as the agent-control layer; use WezTerm as the human-display layer.
171 +- Keep notes in a temp markdown file from the start.
172 +- Record command lines, pane IDs, model/provider when visible, cwd, shell, socket/session/window, and artifact paths.
173 +- Use unique markers for assertions.
174 +- Treat nested agents' claims as untrusted; verify externally.
175 +- Mark harness mistakes immediately; do not mix polluted evidence with product findings.
190 -- tmux is better for agents:
191 - universal CLI, stable pane capture, easy SSH use.
192 -- WezTerm mux is better for GUI/user ergonomics:
193 - tabs, panes, workspaces, fonts, images.
194 -- Best combo:
195 - agent creates tmux sessions; user attaches from WezTerm.
177 +## Common Anti-Patterns
197 -Manual attach from any WezTerm tab:
179 +- `SESSION:main.3` after dynamic splits → use `%pane_id`.
180 +- Generic helper sends `C-c` → split submit vs interrupt helpers.
181 +- Slash command sent while pane is `nu`/`bash` → check `pane_current_command` first.
182 +- Launch Pi then immediately paste prompt → wait for `pi` readiness.
183 +- `sleep 5` as readiness → poll state/artifacts.
184 +- Capture old scrollback as current output → use markers/timestamps and recent captures.
185 +- Continue from command-concatenated pane → declare polluted and open clean pane.
186 +- Complex Bash pasted into Nushell/Fish/PowerShell → orchestrate outside pane or use shell-aware syntax.
187 +- Runaway nested model session → bounded stop plan + direct child signal.
188 +- Killing tmux server without user consent → leave attach/kill commands.
190 +## Visible Terminal / WezTerm
192 +Use tmux for harness logic. If user asks for observable work and WezTerm is available, load the `wezterm` skill and attach visually:
199 194 ```bash
200 -tmux attach -t "$name"
195 +wezterm cli split-pane --right --cwd "$ROOT" -- tmux -L "$SOCKET" attach -t "$SESSION"
203 -If WezTerm CLI is available and user asked for visible work:
205 -```bash
206 -wezterm cli split-pane --right -- tmux attach -t "$name"
207 -# or
208 -wezterm start -- tmux attach -t "$name"
209 -```
211 -Do not depend on WezTerm for harness logic; keep assertions in tmux/files so the
212 -workflow also works over SSH/headless.
214 -## Multi-pane Orchestration
216 -```bash
217 -tmux new-session -d -s "$name" -x 160 -y 48 -n main "cd '$work' && pi"
218 -tmux split-window -t "$name" -h "cd '$work' && tail -f app.log"
219 -tmux split-window -t "$name" -v "cd '$work' && watch -n1 'find . -maxdepth 2 -type f -ls'"
220 -tmux select-pane -t "$name":0.0
221 -```
223 -Useful layouts:
225 -- Left:
226 - Pi / target TUI.
227 -- Right top:
228 - server/log tail.
229 -- Right bottom:
230 - fs/session watcher.
232 -## Creative Workflows
234 -### Real TUI smoke test
236 -Start target in tmux, drive keys, assert pane text and files.
238 -```bash
239 -tmux new-session -d -s "$name" -x 120 -y 40 "cd '$work' && npm run dev:tui"
240 -wait_for 'Ready'
241 -tmux send-keys -t "$name" Tab Enter
242 -pane -200 > "$work/pane.txt"
243 -```
245 -### Busy-state input test
247 -```bash
248 -send 'Run a command that sleeps 10 seconds, then write done.txt.'
249 -sleep 2
250 -send 'While that runs, also write queued.txt with BUSY_MARKER_42.'
251 -wait_for 'BUSY_MARKER_42'
252 -```
254 -Check if input was queued, ignored, interrupted, or applied.
256 -### Server + client + agent
258 -```bash
259 -tmux new-session -d -s "$name" -x 160 -y 48 "cd '$work' && npm run dev"
260 -tmux split-window -t "$name" -h "cd '$work' && pi"
261 -tmux split-window -t "$name" -v "cd '$work' && tail -f app.log"
262 -```
264 -Use Pi pane to modify code while server/log panes keep live feedback visible.
266 -### Long model/provider run
268 -Launch and detach.
269 -Poll periodically.
270 -Preserve pane capture and artifact paths.
272 -```bash
273 -echo "attach: tmux attach -t $name"
274 -echo "workdir: $work"
275 -```
277 -## Assertions
279 -Prefer:
281 -- Unique completion markers.
282 -- Files created in isolated cwd.
283 -- Logs/session JSONL when available.
284 -- Stable pane substrings.
286 -Avoid:
288 -- Full-pane exact snapshots unless testing layout.
289 -- Grepping old scrollback without unique markers.
290 -- Sleeps without semantic readiness checks.
292 -## Cleanup Policy
294 -For normal runs:
296 -```bash
297 -tmux kill-session -t "$name" 2>/dev/null || true
298 -rm -rf "$work"
299 -```
301 -For debugging:
302 -keep session and print attach/workdir commands.
304 -## Benchmark/Fairness Rule
306 -When using tmux for benchmarks, prompts must stay neutral.
307 -Do not mention, require, forbid, or steer toward/away from a tool or extension
308 -under test.
309 -Use tmux as the execution/observation layer only.
198 +If no terminal can be controlled safely, print the attach command and ask the user to attach before continuing visible testing.