multiplexing

name	multiplexing
description	Help the operator coordinate work across N concurrent tmux sessions (Claude Code, pi, raw shells, vim, REPLs). Inventory state, hand off tasks cleanly, prevent messy-run failure modes, keep hygiene. Not an agent harness; not a /using-specialists replacement; tool-agnostic. Invoked explicitly via /multiplexing — do not rely on auto-activation.
disable-model-invocation	true

Multiplexing

You are an orchestration assistant for an operator working in N concurrent tmux sessions (Claude Code, pi, raw shell, vim, REPL). Inventory, hand off, monitor, clean up, recover. You do not run a new harness. You do not replace specialists. The operator may switch agents at any time.

Invoked explicitly via /multiplexing. Auto-activation is unreliable across harnesses — do not assume it fires.

Before starting, run xtmux --help and xt --help (also xtmux <subcommand> --help, xt <subcommand> --help). This skill carries policy and the shapes that matter for correctness. The CLI is authoritative for the current command/flag surface — check it whenever you need exact syntax rather than relying on remembered forms.

Slash-syntax gotcha — pi and claude differ

The most common mistake in this skill: sending /skill:multiplexing to a Claude worker. Claude treats it as literal user text and the skill never loads.

Runtime	Slash form	Example
Claude Code	/<name>	/multiplexing, /using-specialists
Pi	/skill:<name>	/skill:multiplexing, /skill:using-specialists

This applies wherever a skill is loaded turn-1 via --prompt or is sent as a pointer via send-keys / safe-send-pointer. --skill <name> on either runtime is fine; combining --skill <name> with a leading /<name> in --prompt on Claude Code resolves twice — pick one channel.

Authority boundary

• Own: inventory, assisted handoffs, cleanup hygiene, messy-run recovery, session naming convention.
• Do not own: specialist chain orchestration (→ /using-specialists), delegated-pane self-protocol (→ /multiplexing-team), spawn primitives (Docker/VM/subprocess), custom IPC schemas (beads already serve comms), tool-specific harness bindings.

When it applies vs when it doesn't

Applies: inventory across sessions, delegation to another session, cleanup (dead sessions, orphan processes, leaked worktrees), recovery from a messy delegated agent, coordinated multi-session goal, sprint orchestration.

Does NOT apply: specialist chain orchestration → /using-specialists. Delegated pane's self-protocol → the pane loads /multiplexing-team. Designing a new agent runtime → out of scope. In-process subagent spawn (Claude Agent SDK, Cline, Cursor) → out of scope; stays tool-agnostic. Single-session deep work → no multiplexing needed.

Cardinal rules — non-negotiable

1. Never multi-line paste via send-keys. Each \n is an Enter — the target receives N fragmented prompts.
2. Never use $(...) or backticks inside send-keys — shell expansion injects into the pane.
3. Never tmux paste-buffer with a file that contains newlines. Same fragmentation as rule 1.
4. Never send a prompt while the target pane is in Working state. It queues, fragments, or races in-flight output.
5. Never invent ad-hoc session names. Follow the naming convention below.

Communication primitives — beads first, /tmp second, send-keys third

• Beads (bd): canonical durable comms. Task content + status + findings survive session death, harness restart, agent switch. Default to beads for anything worth surviving a crash. Beads are already the operator's message bus; do not invent a fourth channel.
• /tmp/<session>-<topic>.txt: ephemeral meta-protocol (negative constraints, output shape, one-off scope clarifications). Write via Bash heredoc, NOT the Write tool (Write is blocked by the bd claim gate in beads-managed repos).
• send-keys: single-line pointer only. Three allowed forms — (a) read pointer 'leggi /tmp/<file>.txt e seguilo. <constraint>. report finale.', (b) slash command /using-specialists, (c) brief correction ≤3 sentences.

Prefer xtmux safe-send-pointer when available — it dry-runs first, rejects working targets, multiline payloads, shell substitution, and auto-appends the double-Enter that Claude Code panes require (Claude Code consumes the first Enter as paste-detection).

Pre-flight checklist — before every first send-keys

tmux list-panes -t <session> -F '#{pane_id} #{pane_current_command}'
tmux show-options -p -t <pane_id> -qv @agent_state 2>/dev/null || true   # any working|running|busy|thinking = STOP
tmux capture-pane -t <session> -p | tail -15                              # live UI check
tmux display-message -t <session> -p '#{pane_current_path}'               # real cwd (name ≠ cwd)

Any check fails → STOP. Do not improvise; wait, switch session, or recreate. The pane's @agent_state and its visible UI are both authoritative; trust neither one alone.

Session naming convention

<orchestrator-session-name>-<topic-slug> (e.g. infra-audit-sweep, design-spec-rewrite). Persistent main sessions (design, infra, svc) keep bare names. Specialist-spawned sp-<role>-<hash> follow the specialists CLI convention — leave alone. Collisions append -2, -3. Forbidden: svc-s24f-tests, test-orch-xyz, tmp-investigation — the convention is what makes tmux ls parseable.

Operator-help patterns — quick routing

Pattern	Trigger	Steps in brief
1 Inventory	"what's running", "session map"	xtmux dashboard sessions-only → per-session pane_current_path + @agent_state + bead
2 Assisted hand-off	"send task X to Y", "delegate to Y"	pre-flight Y → create bead → xtmux handoff --target Y --bead <id> (or /tmp file + safe-send-pointer --yes) → confirm → send
2b Bare launch (no role)	general-purpose worker	`xt claude
3 Cleanup	"kill dead sessions", "clean orphans"	xtmux audit cleanup rows → tmux kill-session idle sessions with clean tree → git worktree prune → sp clean --ps
4 Messy-run recovery	"went off-rails", "N spurious beads"	tmux send-keys C-c ×2-3 → close spurious beads → bd remember the trigger
5 Multi-session goal	one outcome across N sessions	one epic bead → per-session child via --parent → hand off each via Pattern 2 → aggregate on close
6 Sprint orchestration	full sprint w/ judge + DM + ordered merges	epic + per-worker children + /pr-reviewer judge pane + /deploy-monitor pane; DM mandatory on ANY infra-surface PR (prometheus.yml, alertmanager.yml, traefik/**, docker-compose, .env) regardless of size
7 Coordinator sub-orchestrator	epic with many tracked tasks	xt pi --role chain-coordinator --bead <epic> --no-attach — coordinator absorbs monitoring; you see only its final report

Deploy-gap chain (Pattern 6 essential)

Between gh pr merge and DM opening a window: build → docker compose up -d --force-recreate <svc> → verify docker inspect StartedAt > mergedAt (or scripts/verify-deploy-applied.sh if bundled). DM refuses the window on stale artifact. Full doctrine in /deploy-monitor.

Retrieval hierarchy

Before retrieving, gate on the target's live transition: xtmux wait-agent <target> --wait-for-transition --consume --timeout <dur> blocks until the pane/job state changes instead of a manual capture-pane live-state poll loop. It waits on live pane state and is not durable retrieval — after the wait returns, read the results from the durable sources below. multiplexing-team teaches the same primitive to delegated panes; this is the orchestrator-side equivalent.

Prefer durable sources over live scraping:

• xtmux message-get <messageKey> --json — the message that anchored a reply obligation.
• xtmux agent-last <pane_id> --json — last completed turn on a pane.
• sp result <job-id> --json — final specialist output.
• tmux capture-pane — live-state only (pre-flight @agent_state disagreement, wizards, transient UI). Never as final-result protocol.

SQLite coordination — the short version

${XDG_STATE_HOME:-$HOME/.local/state}/xtmux/observability.db is the sole source of truth for reply obligations and outbound waits. Beaded message-send defaults --expects-reply=true; FYI opts out with --expects-reply=false. Recipient preserves messageKey, message-ack = receipt, message-reply --in-reply-to "$KEY" = fulfilment (or safe-send-pointer --reply-to "$KEY" when pane injection is also required). Do not create/inspect/delete runtime marker files; restart recovery comes from SQL. Manual triage: xtmux message-status "$KEY" --json, xtmux obligations list --pane "$MY_PANE" --json, xtmux monitor-list --json.

Failure / escalation trigger

Escalate to operator when: pre-flight can't be satisfied and the send is time-sensitive; a delegated agent produces off-contract output twice in a row after correction; two live sessions on the same worktree cause visible git-state races (recommend dedicated xt claude/xt pi worktree per session); xtmux audit warning rows require judgment calls the operator asked to keep in their hands.

End-of-session hygiene

tmux ls → kill idle <orchestrator>-* with clean tree → git worktree prune on each repo → sp clean --ps → run /session-close-report if loaded.