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."
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.
13 +Core idea: **spawn process → send real keys → poll pane/artifacts → preserve proof**.
15 +Default mode: detached/background tmux session. The user will not see it unless
16 +they attach or the agent opens/prints an attach command.
18 +##
When To Reach For This 22 +- Interactive CLI/TUI testing: Pi, editors, REPLs, installers, prompts.
23 +- Agent-in-agent workflows: launch `pi` in a pane, steer it, inspect results.
24 +- Long jobs: model calls, builds, servers, watchers, migrations.
25 +- UI verification: status bars, spinners, wrapping, terminal dimensions.
26 +- Timing bugs: input while busy/idle/paused/waiting.
27 +- Multi-process work: app + logs + watcher + nested agent.
28 +- Remote resilience: keep work alive across SSH disconnects.
29 +- Repro sandboxes: isolated cwd/config/session dirs, exact transcript.
33 +- Pure deterministic fns.
34 +- Fast unit checks with structured output.
35 +- Secret-heavy workflows where pane scrollback leaks creds.
36 +- Large regression suites needing strict determinism.
38 +##
Session + Visibility Policy 40 +- Create dedicated sessions by default: `pi_<task>_<shortid>`.
41 +- Do not use the user's active/existing session unless explicitly asked.
42 +- Do not send keys to an existing pane unless the user names that session/pane.
43 +- Kill/reuse only sessions owned by this run and matching your exact name.
44 +- For visible work, print `tmux attach -t "$name"` or open a new terminal tab if
45 + the user asked for visibility.
46 +- For debugging, keep session alive and print attach/workdir paths.
59 +tmux kill-session -t
"$name" 2>/dev/null
|| true
61 +tmux new-session -d -s
"$name" -x 120 -y 40
"cd '$work' && pi" 64 +tmux capture-pane -t
"$name:0.0" -p -S -80
66 +echo "attach: tmux attach -t $name" 67 +echo "workdir: $work" 70 +Keep dimensions fixed. Capture enough history. Prefer stable markers over
71 +whole-screen assertions. Target panes explicitly (`$name:0.0`) when ambiguity
72 +or rapid session changes are possible.
78 + tmux set-buffer -t
"$name" "$1" 79 + tmux paste-buffer -t
"$name" 80 + tmux send-keys -t
"$name" Enter
84 + tmux capture-pane -t
"$name:0.0" -p -S
"${1:--200}" 89 + for i
in {1..60}
; do 91 + pane -300
| grep -q
"$needle" && return 0
101 +tmux send-keys -t
"$name" C-c
102 +tmux send-keys -t
"$name" Escape
103 +tmux send-keys -t
"$name" Tab
106 +##
Short-lived Interactive Programs 108 +If the program exits immediately after success, tmux may destroy the pane before
109 +you capture proof. Keep it alive deliberately:
112 +tmux new-session -d -s
"$name" -x 120 -y 24 \
113 + "cd '$work' && ./cli_under_test; echo __SESSION_ENDED__; exec bash" 116 +Avoid piping interactive programs through `tee`; a pipe can break TTY input.
117 +Prefer `capture-pane` for terminal proof and app-owned log files for structured
120 +##
Pi-In-tmux Pattern 122 +Use nested Pi when you need a real agent session, not just `pi -p` output.
127 +agent_dir
="$work/.pi-agent" 130 +mkdir -p
"$work" "$agent_dir" 131 +tmux kill-session -t
"$name" 2>/dev/null
|| true
133 +tmux new-session -d -s
"$name" -x 140 -y 42 \
134 + "cd '$work' && PI_CODING_AGENT_DIR='$agent_dir' pi" 136 +send
'Create proof.txt containing EXACT_MARKER_9f3a, then print DONE_MARKER_9f3a.' 137 +wait_for
'DONE_MARKER_9f3a' 138 +find
"$work" -maxdepth 3 -type f -print
139 +cat
"$work/proof.txt" 142 +Use unique markers per run. Isolate `PI_CODING_AGENT_DIR` so global sessions,
143 +extensions, auth, prompts, and logs do not contaminate proof.
147 +Use tmux as the agent-control layer; use WezTerm as the human-display layer.
149 +- tmux is better for agents: universal CLI, stable pane capture, easy SSH use.
150 +- WezTerm mux is better for GUI/user ergonomics: tabs, panes, workspaces,
152 +- Best combo: agent creates tmux sessions; user attaches from WezTerm.
154 +Manual attach from any WezTerm tab:
157 +tmux attach -t
"$name" 160 +If WezTerm CLI is available and user asked for visible work:
163 +wezterm cli split-pane --right
-- tmux attach -t
"$name" 165 +wezterm start
-- tmux attach -t
"$name" 168 +Do not depend on WezTerm for harness logic; keep assertions in tmux/files so the
169 +workflow also works over SSH/headless.
171 +##
Multi-pane Orchestration 174 +tmux new-session -d -s
"$name" -x 160 -y 48 -n main
"cd '$work' && pi" 175 +tmux split-window -t
"$name" -h
"cd '$work' && tail -f app.log" 176 +tmux split-window -t
"$name" -v
"cd '$work' && watch -n1 'find . -maxdepth 2 -type f -ls'" 177 +tmux select-pane -t
"$name":0.0
182 +- Left: Pi / target TUI.
183 +- Right top: server/log tail.
184 +- Right bottom: fs/session watcher.
186 +##
Creative Workflows 188 +###
Real TUI smoke test 190 +Start target in tmux, drive keys, assert pane text and files.
193 +tmux new-session -d -s
"$name" -x 120 -y 40
"cd '$work' && npm run dev:tui" 195 +tmux send-keys -t
"$name" Tab Enter
196 +pane -200
> "$work/pane.txt" 199 +###
Busy-state input test 202 +send
'Run a command that sleeps 10 seconds, then write done.txt.' 204 +send
'While that runs, also write queued.txt with BUSY_MARKER_42.' 205 +wait_for
'BUSY_MARKER_42' 208 +Check if input was queued, ignored, interrupted, or applied.
210 +###
Server + client + agent 213 +tmux new-session -d -s
"$name" -x 160 -y 48
"cd '$work' && npm run dev" 214 +tmux split-window -t
"$name" -h
"cd '$work' && pi" 215 +tmux split-window -t
"$name" -v
"cd '$work' && tail -f app.log" 218 +Use Pi pane to modify code while server/log panes keep live feedback visible.
220 +###
Long model/provider run 222 +Launch and detach. Poll periodically. Preserve pane capture and artifact paths.
225 +echo "attach: tmux attach -t $name" 226 +echo "workdir: $work" 233 +- Unique completion markers.
234 +- Files created in isolated cwd.
235 +- Logs/session JSONL when available.
236 +- Stable pane substrings.
240 +- Full-pane exact snapshots unless testing layout.
241 +- Grepping old scrollback without unique markers.
242 +- Sleeps without semantic readiness checks.
249 +tmux kill-session -t
"$name" 2>/dev/null
|| true
253 +For debugging: keep session and print attach/workdir commands.
255 +##
Benchmark/Fairness Rule 257 +When using tmux for benchmarks, prompts must stay neutral. Do not mention,
258 +require, forbid, or steer toward/away from a tool or extension under test.
259 +Use tmux as the execution/observation layer only.