From tmux-pair
This skill should be used when the user asks to "spin up a writer/reviewer pair", "run two agents on this", "pair these agents", "set up an orchestrator + pair", "launch a triple", "use the tmux-pair workflow", or otherwise wants to run two or three coding agents collaboratively in tmux panes wired up via git worktrees. Covers the pair protocol, when to choose pair vs. triple, briefing templates, and recovery from common failure modes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/tmux-pair:tmux-pair-orchestrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run two or three coding agents collaboratively on a single task. Each agent lives in its own tmux pane, all panes share a fresh `git worktree`, and the agents talk peer-to-peer through a small Python helper.
Run two or three coding agents collaboratively on a single task. Each agent lives in its own tmux pane, all panes share a fresh git worktree, and the agents talk peer-to-peer through a small Python helper.
This skill applies whenever the user wants to set up such a pair or triple, monitor it, draft briefings, recover from a stuck loop, or decide between the two modes.
| Mode | Agents | Layout | Master role |
|---|---|---|---|
| pair | Writer + Reviewer | side by side (main-vertical) | active relay between the two agents, hands-on |
| triple | Writer + Reviewer + Orchestrator | Orchestrator on top (full width), Writer/Reviewer below (main-horizontal) | hands-off after spawn, only sees major-event pings |
Default agent assignments (overridable):
codex (terminal-driven, fast on pure code)claude (good at structural review, asks falsifiable questions)claude (recon + briefing + filtering)These are defaults baked into the bundled script. Different agent CLIs work fine — point --writer-agent, --reviewer-agent, --orchestrator-agent at any name registered in ~/.config/tmux-pair/agents.json.
Choose pair when:
Choose triple when:
A triple is overhead for trivial tasks. A pair leaks too much into the master's attention for big ones. See references/triple-vs-pair.md for a longer decision matrix with worked examples.
The protocol is identical for both modes. Only the addressing differs.
Writer makes a meaningful change (one logical step), runs build/lint/tests locally if cheap, and pings the reviewer:
python3 <plugin>/scripts/tmux_pair.py send <reviewer-pane> "REVIEW-READY: <one-line summary>"
Reviewer reads the change, the tests, and the writer's summary. Replies with one of:
REVIEW: APPROVE — change is good as-is.REVIEW: <findings> — concrete, falsifiable findings (file:line, problem, suggested direction). No vague "consider improving".If APPROVE, writer commits (Conventional Commits, no --no-verify, no AI co-author trailer) and pings DONE: <commit-sha> <branch-state>.
If findings, writer fixes, pings REVIEW-READY again. Loop.
If the pair stalls — disagreement, missing info, suspected upstream bug — either side pings BLOCKER: <what> (in pair mode: to master; in triple mode: to orchestrator).
The full protocol with all event types and edge cases lives in references/pair-protocol.md.
The point of the triple is that the master delegates the relay to the orchestrator. The master:
[Orchestrator <window>] MAJOR-STEP / BLOCKER / DONE / ABORTDONEThe orchestrator does:
The orchestrator does NOT code, does NOT review, does NOT commit, does NOT decide on cleanup.
Pair (main-vertical):
+---------+---------+
| | |
| Writer | Reviewer|
| | |
+---------+---------+
Triple (main-horizontal):
+---------------------+
| Orchestrator |
+----------+----------+
| Writer | Reviewer |
+----------+----------+
Both layouts are forced via select-layout after spawning, so pane order matters: the orchestrator (in triple mode) or the writer (in pair mode) must be the first pane in the window.
Both commands assume the master is already inside a tmux session.
/pair <project-path> <base> <feature> [task...]
/triple <project-path> <base> <feature> [task...]
The script:
<project-parent>/<project-basename>-wt-<feature>, branch feature/<feature>, from <base>. If the branch already exists, it is reused.<project-basename>-<feature> (truncated to 30 chars).sleep 14 && send, so the agents have time to boot before the message lands.Each role has a template in examples/:
examples/writer-briefing.md — implementation brief: pointers, deliverables, pair protocol with reviewer pane id, standards.examples/reviewer-briefing.md — review brief: what to check (falsifiable), how to phrase findings, pair protocol with writer pane id.examples/orchestrator-briefing.md — full duty list: recon, brief engineers, watch loop, report to master.These are starting points. Adapt to the task at hand. The bundled script generates a baseline briefing automatically; the templates are useful when overriding the briefing or when the orchestrator writes one from scratch after recon.
The cross-pane primitive is tmux_pair.py send:
python3 <plugin>/scripts/tmux_pair.py send <pane-id> "<message>"
Multi-line messages are submitted via load-buffer + paste-buffer to avoid the issue where some agent TUIs interpret each newline as a submit. Single-line messages use plain send-keys -l. After the text, the helper sends Enter three times with small gaps; this works around agent TUIs that ignore the first Enter when a tool call is in flight. Override with --no-enter if needed.
The full list with diagnostics and recovery steps lives in references/failure-modes.md. The most common ones:
git push happened despite the brief saying "wait for master". Cause: briefing missing or weakly worded. Fix: spell out the push gate explicitly in the briefing template.After DONE:
cd <project-path>
git worktree remove ../<project-name>-wt-<feature>
git branch -d feature/<feature> # after merge
tmux kill-window -t <window-name>
Cleanup is the master's call. Neither the orchestrator nor the engineers should remove worktrees, kill windows, or delete branches during a run.
references/pair-protocol.md — full event vocabulary, edge cases, escalation rules, and end-of-run handshake.references/triple-vs-pair.md — decision matrix with worked examples for choosing the mode.references/failure-modes.md — common failure modes with diagnostics, recovery steps, and prevention.examples/writer-briefing.md — writer briefing template.examples/reviewer-briefing.md — reviewer briefing template.examples/orchestrator-briefing.md — orchestrator briefing template (the largest of the three).Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub derveloper/derveloper-skills --plugin tmux-pair