repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

add tmux agent harness skill

5613d0e38bc9eb9af5bcb14113e93044dc52c4bf

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

skills/tmux/SKILL.md

Added
new file mode 100644
1 +---
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."
4 +license: GPLv3
5 +compatibility: "Requires tmux; pairs well with Pi CLI"
6 +---
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.
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
20 +Use tmux for:
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.
31 +Do not use tmux for:
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.
48 +## Default Harness
50 +```bash
51 +set -euo pipefail
53 +id=$(date +%s)
54 +name="pi_task_$id"
55 +work="/tmp/$name"
57 +rm -rf "$work"
58 +mkdir -p "$work"
59 +tmux kill-session -t "$name" 2>/dev/null || true
61 +tmux new-session -d -s "$name" -x 120 -y 40 "cd '$work' && pi"
63 +# readiness/pane probe
64 +tmux capture-pane -t "$name:0.0" -p -S -80
66 +echo "attach: tmux attach -t $name"
67 +echo "workdir: $work"
68 +```
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.
74 +## Send Input Safely
76 +```bash
77 +send() {
78 + tmux set-buffer -t "$name" "$1"
79 + tmux paste-buffer -t "$name"
80 + tmux send-keys -t "$name" Enter
83 +pane() {
84 + tmux capture-pane -t "$name:0.0" -p -S "${1:--200}"
87 +wait_for() {
88 + local needle="$1"
89 + for i in {1..60}; do
90 + sleep 1
91 + pane -300 | grep -q "$needle" && return 0
92 + done
93 + pane -300 >&2
94 + return 1
96 +```
98 +Special keys:
100 +```bash
101 +tmux send-keys -t "$name" C-c
102 +tmux send-keys -t "$name" Escape
103 +tmux send-keys -t "$name" Tab
104 +```
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:
111 +```bash
112 +tmux new-session -d -s "$name" -x 120 -y 24 \
113 + "cd '$work' && ./cli_under_test; echo __SESSION_ENDED__; exec bash"
114 +```
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
118 +proof.
120 +## Pi-In-tmux Pattern
122 +Use nested Pi when you need a real agent session, not just `pi -p` output.
124 +```bash
125 +name=pi_nested
126 +work=/tmp/$name
127 +agent_dir="$work/.pi-agent"
129 +rm -rf "$work"
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"
140 +```
142 +Use unique markers per run. Isolate `PI_CODING_AGENT_DIR` so global sessions,
143 +extensions, auth, prompts, and logs do not contaminate proof.
145 +## WezTerm + tmux
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,
151 + fonts, images.
152 +- Best combo: agent creates tmux sessions; user attaches from WezTerm.
154 +Manual attach from any WezTerm tab:
156 +```bash
157 +tmux attach -t "$name"
158 +```
160 +If WezTerm CLI is available and user asked for visible work:
162 +```bash
163 +wezterm cli split-pane --right -- tmux attach -t "$name"
164 +# or
165 +wezterm start -- tmux attach -t "$name"
166 +```
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
173 +```bash
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
178 +```
180 +Useful layouts:
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.
192 +```bash
193 +tmux new-session -d -s "$name" -x 120 -y 40 "cd '$work' && npm run dev:tui"
194 +wait_for 'Ready'
195 +tmux send-keys -t "$name" Tab Enter
196 +pane -200 > "$work/pane.txt"
197 +```
199 +### Busy-state input test
201 +```bash
202 +send 'Run a command that sleeps 10 seconds, then write done.txt.'
203 +sleep 2
204 +send 'While that runs, also write queued.txt with BUSY_MARKER_42.'
205 +wait_for 'BUSY_MARKER_42'
206 +```
208 +Check if input was queued, ignored, interrupted, or applied.
210 +### Server + client + agent
212 +```bash
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"
216 +```
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.
224 +```bash
225 +echo "attach: tmux attach -t $name"
226 +echo "workdir: $work"
227 +```
229 +## Assertions
231 +Prefer:
233 +- Unique completion markers.
234 +- Files created in isolated cwd.
235 +- Logs/session JSONL when available.
236 +- Stable pane substrings.
238 +Avoid:
240 +- Full-pane exact snapshots unless testing layout.
241 +- Grepping old scrollback without unique markers.
242 +- Sleeps without semantic readiness checks.
244 +## Cleanup Policy
246 +For normal runs:
248 +```bash
249 +tmux kill-session -t "$name" 2>/dev/null || true
250 +rm -rf "$work"
251 +```
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.