/tmux-agent-comms

name: tmux-agent-comms
description: "Manage AI agents in tmux: spawn sessions, send messages, wait, capture replies, inspect fleets, and tear down safely. Use for tmux-hosted CLI agents. Don't use for SSH, GNU screen, or GUI apps."
license: MIT
compatibility: "Requires `tmux` on PATH. Optional Python 3 for wait/preflight/broadcast helpers."
effort: medium
metadata:
  version: 2.4.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Tmux Agent Comms

Manage CLI agents in separate tmux sessions. Treat each session as one agent; orchestrate it with `send-keys` and `capture-pane`. Relay reply deltas instead of whole screens to protect the context/token budget.

New sessions open in a terminal tab inside the current app by default. If the environment cannot open one, create the session detached and print the exact attach command. Never invoke `attach-session` from a non-TTY tool.

Use `herdr-agent` instead when agents live in Herdr.

When to Use

Route directly to the required mode; do not read unrelated references.

| Task | Start | |---|---| | Spawn an agent | Phase 1 | | Message or steer an existing agent | Phase 2 | | Read a pane, show status, or inspect | Phase 5 | | Broadcast to a fleet | Phase 6 | | Shut down an agent | Phase 6 | | Main agent's own context is filling up | Phase 7 HANDOFF |

Prerequisites

1. Run `command -v tmux`. If it prints nothing, stop and report `BLOCKED` with the install command (`brew install tmux` or `apt install tmux`). 2. Before any spawn, send, wait, or broadcast, set `$here` to this skill's `scripts/` directory with the resolver in `references/tmux-recipes.md` (*Resolve scripts/*). Every helper call below runs from `$here`. 3. Before writing to a session, confirm its exact name (Phase 2) and capture its pane once.

Critical Rules

1. **Confirm destructive actions.** Never send `exit`/`/quit`, kill a session, or kill the server without explicit approval. 2. **Fail closed before every send.** Only preflight exit 0 is sendable; every other code means do not send. Codes are defined once, in *the exit-code table* (`references/delivery-and-waiting.md`). 3. **Use a fresh proof cycle.** Every message needs a new baseline file and split completion marker. Never reuse either for a follow-up. 4. **Send text and Enter separately.** For multiline/code-heavy text, use tmux paste-buffer; see `references/tmux-recipes.md`. 5. **Bound waiting.** Use a wall-clock cap or at most 2–3 re-waits. Surface a stall instead of polling forever. 6. **Keep reads bounded.** Start with `capture-pane -S -40` and widen only when the reply is truncated. 7. **Escalate blocked panes.** A trust/auth/permission dialog requires a human; do not type task text into it. 8. **Run exactly one orchestrator.** Only the current main agent writes to fleet sessions. Orchestrator is a role, not a session: after a Phase 7 HANDOFF ack, the outgoing agent goes read-only and issues no further `send-keys`, spawns, or kills. 9. **Gate your own context.** Self-check at every Phase 7 gate point; at or above the threshold, HANDOFF instead of continuing to fill this window.

Workflow

Run Phases 1–6 in order for a send. A read-only status/inspect operation may jump to Phase 5. Phase 7 is the orchestrator's own context gate, evaluated at its named gate points rather than in sequence.

Phase 1 — Create or Discover

List sessions:

tmux list-sessions 2>/dev/null || echo "no tmux server running yet"

Name new sessions `<folder>-<short-task>` (for example, `myrepo-reviewer`). Avoid collisions with `tmux has-session` before creating one. Launch the requested interactive CLI in a new app terminal tab; if no tab facility exists, use detached mode and print `tmux attach-session -t <name>` for the human.

After spawn, require readiness before assigning work:

python3 "$here/wait_for_idle.py" "$name" --ready --timeout 60 --no-print

Read the result off *the exit-code table* in `references/delivery-and-waiting.md`; only exit 0 clears the session for work. Spawn fleets first, then check readiness concurrently. Read `references/tmux-recipes.md` for naming, tab/detached branches, script resolution, and fleet readiness.

**Complete when:** every created session has an exact name and passes the ready gate, or the failure is surfaced without sending work.

Phase 2 — Resolve the Exact Target

tmux has-session -t "$target" 2>/dev/null

If `has-session` fails, run `tmux list-sessions`. If exactly one listed session name contains the requested name (for example, `myrepo-reviewer` for `reviewer`), use that exact name. If none or several match, ask the user which session to use; never guess. To target one pane, use `session:window.pane`.

**Complete when:** one existing tmux target is confirmed.

Phase 3 — Baseline, Preflight, and Send

Read `references/delivery-and-waiting.md` before sending. Follow its contract:

1. Capture `-S -80` to a temporary baseline file. 2. Mint a fresh suffix and define `completion_marker="TAC_DONE_$suffix"`. 3. Append an instruction that prints `TAC_DONE_` joined with the suffix only after completion. 4. Run `preflight_send.py` immediately before dispatch; send only on exit 0. 5. Send message text, then send `Enter` in a separate call. 6. Check once for post-send activity against the baseline. If unchanged, re-preflight before one recovery Enter; fail if still unchanged.

On multiline/code-heavy input, use paste-buffer rather than shell escaping. Always clean up temporary files on failure.

**Complete when:** post-send activity proves delivery, or a descriptive failure is surfaced. Typed text alone is not proof.

Phase 4 — Wait and Verify

python3 "$here/wait_for_idle.py" "$target" --timeout 180 --scrollback 80 \
  --baseline-file "$baseline_file" --completion-marker "$completion_marker"
rc=$?
rm -f "$baseline_file"

Handle `rc` per *the exit-code table* in `references/delivery-and-waiting.md`. Before relaying an actionable result