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."
5 5 compatibility: "Requires tmux; pairs well with Pi CLI"
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.
14 -**spawn process → send real keys → poll pane/artifacts → preserve proof**.
12 +##
Non-Negotiable Protocol 17 -detached/background tmux session.
18 -The user will not see it unless they attach or the agent opens/prints an attach
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 26 +| State | Evidence | Allowed action |
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.
30 - model calls, builds, servers, watchers, migrations.
32 - status bars, spinners, wrapping, terminal dimensions.
34 - input while busy/idle/paused/waiting.
35 -- Multi-process work:
36 - app + logs + watcher + nested agent.
38 - keep work alive across SSH disconnects.
40 - isolated cwd/config/session dirs, exact transcript.
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.
38 +name
="pi_task_$(date +%s)" 40 +notes
="$work/notes.md" 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")" 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
57 +Invariant when requested: exactly one tmux server/session/window; panes are OK.
61 +Use these patterns, adapted to your socket/session names.
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}"; }
69 + tmux -L
"$SOCKET" list-panes -t
"$SESSION:main" \
70 + -F
'#{pane_id} idx=#{pane_index} title=#{pane_title} cmd=#{pane_current_command}' 98 - tmux capture-pane -t
"$name:0.0" -p -S
"${1:--200}" 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 103 - for i
in {1..60}
; do 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 +##
Shell-Aware Launch 93 +Probe the user's shell/terminal before pane work:
96 +USER_SHELL
="$(basename "${SHELL:-unknown}")" 97 +printf 'shell=%s\nWEZTERM_PANE=%s TERM_PROGRAM=%s\n' \
98 + "$USER_SHELL" "${WEZTERM_PANE-}" "${TERM_PROGRAM-}" 101 +For pane launches, keep commands simple. Nushell/Fish/PowerShell use `;`, not Bash `&&`.
105 + local pane
="$1" root
="$2" cmd
="$3" shell
106 + shell
="$(pane_cmd "$pane")" 108 + nu
|nu.exe
|fish
|pwsh
|powershell.exe
) send_line
"$pane" "cd '$root'; $cmd" ;;
109 + *) send_line
"$pane" "cd '$root' && $cmd" ;;
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.
121 + for _
in {1..60}
; do 122 + [ "$(pane_cmd "$pane")" = pi
] || { sleep 1
; continue; }
105 - pane -300
| grep -q
"$needle" && return 0
125 + [ "$(pane_cmd "$pane")" = pi
] && return 0
127 + capture
"$pane" -80
>&2 115 -tmux send-keys -t
"$name" C-c
116 -tmux send-keys -t
"$name" Escape
117 -tmux send-keys -t
"$name" Tab
120 -##
Short-lived Interactive Programs 122 -If the program exits immediately after success, tmux may destroy the pane before
124 -Keep it alive deliberately:
127 -tmux new-session -d -s
"$name" -x 120 -y 24 \
128 - "cd '$work' && ./cli_under_test; echo __SESSION_ENDED__; exec bash" 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
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:
144 -tmux list-panes -a -F
'#{session_name}:#{window_index}.#{pane_index} #{pane_current_command}' 149 - tmux send-keys -t
"$target" C-u
150 - printf '%s' "$1" | tmux load-buffer -
151 - tmux paste-buffer -t
"$target" 152 - tmux send-keys -t
"$target" Enter
132 + local pane
="$1" text
="$2" 133 + require_cmd
"$pane" pi
|| return 1
134 + tmux -L
"$SOCKET" send-keys -t
"$pane" C-u
136 + send_line
"$pane" "$text" 155 -pi_send
'/my-command arg' 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
161 -For prototype extensions, avoid command argument completions unless completion
162 -behavior is under test.
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:
167 -agent_dir
="$work/.pi-agent" 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.
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.
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:
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:
206 -wezterm cli split-pane --right
-- tmux attach -t
"$name" 208 -wezterm start
-- tmux attach -t
"$name" 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 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
230 - fs/session watcher.
232 -##
Creative Workflows 234 -###
Real TUI smoke test 236 -Start target in tmux, drive keys, assert pane text and files.
239 -tmux new-session -d -s
"$name" -x 120 -y 40
"cd '$work' && npm run dev:tui" 241 -tmux send-keys -t
"$name" Tab Enter
242 -pane -200
> "$work/pane.txt" 245 -###
Busy-state input test 248 -send
'Run a command that sleeps 10 seconds, then write done.txt.' 250 -send
'While that runs, also write queued.txt with BUSY_MARKER_42.' 251 -wait_for
'BUSY_MARKER_42' 254 -Check if input was queued, ignored, interrupted, or applied.
256 -###
Server + client + agent 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" 264 -Use Pi pane to modify code while server/log panes keep live feedback visible.
266 -###
Long model/provider run 270 -Preserve pane capture and artifact paths.
273 -echo "attach: tmux attach -t $name" 274 -echo "workdir: $work" 281 -- Unique completion markers.
282 -- Files created in isolated cwd.
283 -- Logs/session JSONL when available.
284 -- Stable pane substrings.
288 -- Full-pane exact snapshots unless testing layout.
289 -- Grepping old scrollback without unique markers.
290 -- Sleeps without semantic readiness checks.
297 -tmux kill-session -t
"$name" 2>/dev/null
|| true
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
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.