1---
2name: tmux-multi-agent
3description: Launch and manage bounded Codex or Claude workers in tmux with inspectable artifacts. Use it when work splits cleanly by file ownership, when a dedicated reviewer should run separately from the implementer, when a worker must stay alive across multiple turns, or when the user explicitly asks to open or show the worker in a real terminal window on their desktop.
4---
5 
6# Tmux Multi Agent
7 
8Use this skill when parallel agent work is actually cheaper than doing the task in one session, or when the user wants a long-running worker they can inspect directly. The coordinator stays in the current shell, launches workers in tmux, gives each worker a bounded task, and records the run on disk so another human or agent can inspect it later.
9 
10## When Not To Use It
11 
12- Do not use this for small edits, single-file fixes, or tasks that need constant back-and-forth.
13- Do not use it when multiple workers would touch the same files at the same time.
14- Do not use it if you cannot run tmux plus at least one of `claude` or `codex`.
15 
16## Preconditions
17 
18Verify the tools first:
19 
20```bash
21command -v tmux
22command -v claude
23command -v codex
24```
25 
26The bundled launcher defaults to:
27 
28```bash
29TA_CLAUDE_CMD='claude --dangerously-skip-permissions'
30TA_CODEX_CMD='codex --dangerously-bypass-approvals-and-sandbox'
31```
32 
33These flags are required for non-interactive orchestration. Override via env vars if your setup uses different approval modes.
34 
35Optional env vars:
36 
37- `TA_SESSION_ID`: run id used to prefix tmux session names
38- `TA_CWD`: working directory for launched workers; defaults to the current directory
39 
40## 1. Meta Step
41 
42Before spawning workers, write a grounded brief. Do not launch sessions until this exists.
43 
44The brief must state:
45 
46- scope
47- out-of-scope
48- exact files or directories each worker may touch
49- verification commands the reviewer must run
50- definition of done with checkable criteria
51 
52Example:
53 
54```bash
55export SESSION_ID="$(head -c2 /dev/urandom | xxd -p)"
56export SESSION_DIR=".tmux-multi-agent/sessions/${SESSION_ID}"
57mkdir -p "${SESSION_DIR}"/{tasks,handoffs,reviews,artifacts}
58 
59cat > "${SESSION_DIR}/brief.md" <<'EOF'
60# Scope
61Implement the requested change in the target repo.
62 
63# Out Of Scope
64Anything not required for this task.
65 
66# Owned Files
67- worker-a: path/glob-a
68- worker-b: path/glob-b
69 
70# Verification Commands
71- bun test ...
72- bun run ...
73 
74# Definition Of Done
75- exact behavior exists
76- verification commands pass
77- reviewer writes approval or findings
78EOF
79```
80 
81## 2. Session Setup
82 
83Export the run id before using the helper script so every worker session is namespaced:
84 
85```bash
86export SESSION_ID="${SESSION_ID:-$(head -c2 /dev/urandom | xxd -p)}"
87export TA_SESSION_ID="${SESSION_ID}"
88export SESSION_DIR=".tmux-multi-agent/sessions/${SESSION_ID}"
89mkdir -p "${SESSION_DIR}"/{tasks,handoffs,reviews,artifacts}
90```
91 
92Naming rules:
93 
94- every tmux session must be `${SESSION_ID}-<worker-name>`
95- the helper applies that prefix automatically when `TA_SESSION_ID` or `SESSION_ID` is set
96- `ta kill all` only kills sessions with the current session id prefix
97 
98Helper path:
99 
100- local/live copies may expose `scripts/ta`
101- stored marketplace bundles may expose `scripts/ta.sh` when the plain `ta` filename is inconvenient for packaging
102- `scripts/ta.sh` must stay functionally identical to `scripts/ta`; treat it as a compatibility mirror, not a fork
103- prefer `scripts/ta` in live checkouts; use `scripts/ta.sh` only when that is the path the bundle exposes
104 
105## 3. Launch Workers
106 
107Launch bounded workers from the repo root:
108 
109```bash
110TA_BIN="${TA_BIN:-$( [ -x scripts/ta ] && printf '%s' scripts/ta || printf '%s' scripts/ta.sh )}"
111ui_session="$(${TA_BIN} claude ui)"
112review_session="$(${TA_BIN} codex review)"
113```
114 
115Useful commands:
116 
117```bash
118${TA_BIN} ls
119${TA_BIN} attach "${ui_session}"
120${TA_BIN} attach "${review_session}"
121```
122 
123## 3a. Open The Worker In A Real Desktop Window
124 
125If the user says things like "show it on the screen", "open it in a window", "launch it for me on my computer", or otherwise clearly wants the worker visible in a normal terminal window, do not stop at `ta read` output or an in-chat pane dump. Open a real desktop terminal and attach it to the managed tmux session.
126 
127First verify that a GUI session and terminal emulator exist:
128 
129```bash
130printf 'DISPLAY=%s\nWAYLAND_DISPLAY=%s\nXDG_CURRENT_DESKTOP=%s\n' \
131  "${DISPLAY:-}" "${WAYLAND_DISPLAY:-}" "${XDG_CURRENT_DESKTOP:-}"
132command -v gnome-terminal || command -v kitty || command -v x-terminal-emulator
133${TA_BIN} ls
134```
135 
136Preferred GNOME example:
137 
138```bash
139export DISPLAY="${DISPLAY:-:0}"
140export WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}"
141nohup gnome-terminal --title "Codex review" \
142  -- bash -lc "tmux attach-session -t ${review_session} || exec bash" \
143  >/tmp/tmux-window.log 2>&1 &
144```
145 
146Kitty fallback:
147 
148```bash
149export DISPLAY="${DISPLAY:-:0}"
150nohup kitty --title "Codex review" \
151  bash -lc "tmux attach-session -t ${review_session} || exec bash" \
152  >/tmp/tmux-window.log 2>&1 &
153```
154 
155Rules:
156 
157- Prefer opening the already running managed session instead of launching a second duplicate worker.
158- Use the exact session name from `${TA_BIN} ls`.
159- Only tell the user it is "open" after the desktop terminal process starts successfully.
160- If tmux attach inside the current chat shell fails because the terminal does not support clear or alternate-screen behavior, opening an external desktop terminal is the correct recovery path.
161 
162## 4. Send Bounded Tasks
163 
164Every worker task must be self-contained. It should reference the brief, state owned files, forbid out-of-scope edits, and say exactly where the worker must write its handoff or review.
165 
166Example worker task:
167 
168```bash
169cat > "${SESSION_DIR}/tasks/ui.md" <<EOF
170Read ${SESSION_DIR}/brief.md first.
171Own only src/components/settings/*.
172Do not touch API, database, CI, or build files.
173Run only the verification commands that apply to your slice if feasible.
174Write your handoff to ${SESSION_DIR}/handoffs/ui.md with:
175- files changed
176- commands run
177- tests run or not run
178- blockers or open questions
179EOF
180 
181${TA_BIN} send "${ui_session}" "${SESSION_DIR}/tasks/ui.md"
182```
183 
184Rules:
185 
186- split by file ownership, not vague themes
187- do not assign the same file tree to multiple workers at once
188- require written handoffs; do not trust scrollback alone
189- use `${TA_BIN} send <session> <file-or-text>` for the common path
190- use `${TA_BIN} send --file <session> <path>` or `${TA_BIN} send --text <session> <text>` when the payload is ambiguous
191- the helper uses bracketed paste and a short pre-submit settle delay for Codex; do not add your own manual Enter unless you are deliberately recovering a broken session
192 
193## 5. Monitoring
194 
195Use the helper script instead of ad hoc tmux commands:
196 
197```bash
198${TA_BIN} ls
199${TA_BIN} wait "${ui_session}"
200${TA_BIN} read "${ui_session}" 80
201${TA_BIN} watch "${ui_session}"
202```
203 
204Discipline:
205 
206- use `ta wait` for blocking waits when you only need exit status; use `ta watch` when you want the final assistant text as soon as the turn completes
207- use `ta read` for detail at most once per minute unless something broke
208- treat `busy` as "leave it alone"
209- if a worker is `idle`, read the tail before sending another prompt
210 
211Monitoring model:
212 
213- the helper writes sidecar state under `${SESSION_DIR}/ta-state/<session>/`
214- `session.json` stores the last known state, launch cwd, last send timestamp, and any bound JSONL path
215- `events.ndjson` is an append-only event log for launch, send, state changes, and JSONL binding
216- for Codex and Claude, the helper first tries to bind the session to the agent's JSONL log via the tmux pane process tree and open file descriptors
217- if no bound JSONL is available, `ta` falls back to pane-based heuristics instead of guessing from prompt characters
218 
219Busy detection details:
220 
221- Codex: `idle` means a `final_answer` record was observed after the last helper `send`
222- Claude: `idle` means the last assistant record after the last helper `send` has `stop_reason=end_turn`
223- pane fallback still looks for recent output such as `Working (...)`, `Churned`, `Computing`, `Flowing`, `• Ran`, `• Explored`, `• Searched`, or `• Called`
224- do not use prompt characters as an idle signal
225 
226## 6. Review And Verification
227 
228Review must happen in a fresh session. Do not reuse the implementation worker as the reviewer.
229 
230Typical loop:
231 
2321. implementation worker writes `handoffs/<worker>.md`
2332. coordinator inspects the handoff and changed files
2343. fresh reviewer session reads the brief, handoff, and diff
2354. reviewer runs actual verification commands
2365. reviewer writes findings or approval to `reviews/<worker>.md`
2376. coordinator records the commands and outcomes in `artifacts/verification.md`
238 
239Example review task:
240 
241```bash
242cat > "${SESSION_DIR}/tasks/review.md" <<EOF
243Read ${SESSION_DIR}/brief.md first.
244Read ${SESSION_DIR}/handoffs/ui.md and inspect the diff.
245Review for correctness, regressions, missing tests, and scope creep.
246Run the verification commands from the brief yourself.
247Write findings or approval to ${SESSION_DIR}/reviews/review.md.
248Record command output and pass/fail status in ${SESSION_DIR}/artifacts/verification.md.
249EOF
250 
251${TA_BIN} send "${review_session}" "${SESSION_DIR}/tasks/review.md"
252${TA_BIN} wait "${review_session}" 600
253```
254 
255Worker claims are not verification. The reviewer or coordinator must run the commands.
256 
257## 7. Failure Recovery
258 
259Keep recovery tied to observable failures:
260 
261- launch failed: inspect `${TA_BIN} read <session> 100`, then relaunch
262- worker never leaves `busy`: read the tail, then either wait longer or send one narrowed follow-up
263- worker went idle with no handoff: ask for the missing artifact, not a full restatement of the task
264- conflicting edits: stop parallel work on the shared files and reassign ownership
265- claimed completion without evidence: require a handoff with files changed and commands run
266- reviewer found concrete issues: send a new bounded task with those findings only
267 
268If the same slice fails twice, reduce scope or switch owners.
269 
270## 8. Routing Heuristic
271 
272These are heuristics, not laws. Prefer the worker that matches the repo and the observable problem.
273 
274| Work shape | Default | Why | Caveat |
275| --- | --- | --- | --- |
276| Backend, infra, debugging, review, verification | Codex | Usually stronger on correctness, systems work, and findings-first review | Keep the task bounded; do not ask for vague polish |
277| Frontend UI, docs, copy, readability refactors | Claude | Usually better at presentation, polish, and large wording rewrites | Route technical verification back to Codex or another strict reviewer |
278| Full-stack split with clean ownership | Claude for UI, Codex for backend/review | Lets each worker stay inside a real file boundary | Do not let both workers edit the same files concurrently |
279| Pure planning with no grounding | Neither by default | Plans drift fast without repo evidence | Write the brief from the actual code and user constraints first |
280 
281## 9. Artifact Contract
282 
283After a real run, these artifacts must exist under `${SESSION_DIR}`:
284 
285- `brief.md`
286- `tasks/<worker>.md` for every launched worker
287- `handoffs/<worker>.md` for every implementation worker
288- `reviews/<worker>.md` for every reviewed slice
289- `artifacts/verification.md` with exact commands and outcomes
290 
291Optional artifacts:
292 
293- `artifacts/*.log` or `artifacts/*.txt` for saved command output
294- extra handoffs or follow-up tasks when review required another pass
295 
296If these files do not exist, the run is not inspectable enough to trust.
297