--- name: tmux-agent-orchestrator description: Starts and coordinates multiple Pi coding agents in a monitorable tmux grid through an event-driven private broker, with one writer, independent review, optional technical probe, Playwright tester, Django expert, structured reports, token usage, messaging, restart, and cleanup. Use for delegated implementer/reviewer loops or specialist review across projects. compatibility: Requires Pi (verified with 0.87.1), Python 3.11+, and tmux 3.2+. Other Pi versions are not covered by a compatibility matrix. tmux 3.5+ with extended-keys csi-u is recommended. --- # Pi Tmux Orchestrator Prefer the compact extension surface—`/or-dashboard`, `/or-start`, `/or-models`, `/or-send`, and `/or-stop`—when interacting through Pi. The dashboard lists runs, shows concise help/about metadata, runs doctor only after `d`, attaches with Enter, and confirms stop with `x`. Duplicate `/orchestrator-*` and read-only helper slash commands are intentionally not registered. The bounded `tmux_orchestrator` tool exposes the complete authoritative control plane. New starts are watched automatically; use its `watch` action for an existing run so the parent receives lifecycle and final updates. `/or-send` and `/or-stop` with an omitted session list valid running orchestrations for explicit selection; model-tool calls should continue to use an exact session whenever multiple runs exist. Use `attach` when the user wants to enter, navigate, or directly steer the worker panes; it switches the invoking Pi's existing tmux client into the grid while keeping that Pi and its observer alive. Attach watches future transitions but does not replay an existing initial actionable outcome as a task in the invoking Pi. Prefix then `L` detaches from the grid by returning to the same invoking Pi and original project context without stopping the workers. The dashboard overlay uses explicit refresh and Enter-based selection because Pi's public overlay API does not expose row-click callbacks. The standalone `pi-tmux-agents` CLI fallback is authoritative; do not hand-build panes, file handoffs, relay scripts, or polling loops. ## Operating rules 1. Resolve the target project and read its governing instructions before launch. 2. Never approve an unfamiliar project. Parent trust does not transfer to child Pi sessions. 3. Keep one writer: only the implementer may edit tracked files. Other roles are workflow-read-only but retain `bash` for verification and are not OS-sandboxed. 4. Keep credentials, private documents, provider bodies, raw errors, diffs, and logs out of tasks and structured reports. 5. Honor an explicit `economy`, `balanced`, `thorough`, or strict user-global custom profile through `profile`. Profiles change thinking only and never weaken review, tools, or routing. If omitted, use the exact canonical project mapping, configured global default, or packaged compatibility default in that order. 6. Honor an explicit `implementationFlow`; when omitted, use the exact-project default or `single`. Choose `phased` for complex work that benefits from read-only discovery before editing. Do not make a separate classifier model request. 7. Honor explicit user provider/model/thinking requests through `useParentModel` or `modelOverrides`; these win over exact-project/global model policy and profile thinking. Use the bounded `models` action to resolve exact available IDs; never invent IDs or inspect credentials. 8. Honor explicit per-run budget requests through `budgetOverrides`; never infer hard thresholds. Omitted values use the strict external user-global policy and packaged warn-only defaults. 9. When the user asks the orchestrator to decide worker count, eligible built-in/custom specialist roles, models, or thinking before launch, pass `dynamicPlan=true`. This requires separate confirmation for one bounded provider-backed preflight call and another confirmation for launch; the terminal equivalent requires all of `--dynamic-plan --authorize-planning --yes`. TypeSafe authentication configured through `/login typesafe` or the `TYPESAFE_API_KEY` environment fallback selects the bundled direct `jev-latest` typed-decision adapter; when TypeSafe authentication is absent, an exact per-run Pi `decisionModel` wins over the strict user-global exact Pi preferred identity and ordered cross-provider fallbacks. No eligible fallback identity must follow configured cancellation or an explicitly confirmed static/manual fallback. Pi decision-call thinking follows decision-model policy; worker thinking may use each model's supported levels through `max`; exact-project custom roles are candidates only after registry/resource validation, and `projectCustomRoles=false` excludes them. Dynamic planning uses Pi's bounded available/scoped catalog with a non-secret capability/cost-hint projection and no operator model allowlist; choose the smallest sufficient model from listed technical needs and declared catalog rates without inferring quality, skill, latency, or reliability from names. Declared rates are not observed spend. Accepted plans are bound to private inputs and resolved policy/catalog/resource/capability metadata and revalidated after preview; retained provenance is body-free. Never put the TypeSafe key in arguments/configuration or claim the extra call saves cost or improves quality without evidence. 10. Configured specialists use conservative deterministic gates after launch. Pass `forceSpecialists` or `--force-specialist ROLE` only when the user explicitly requires that enabled role to run regardless of a skip predicate. Exact-project `customRoles` come from validated user-global configuration; pass `projectCustomRoles=false` only to omit them. Never invent custom role IDs, tools, or contracts. 11. Worker skill discovery is disabled. Pass `workerSkills` or `--worker-skill ROLE=PATH` only for exact Markdown files the user explicitly reviewed; never infer or auto-load a skill. 12. Orchestration workers bound read/grep/bash results before the next provider call. Follow emitted offset, refined-search, and targeted full-output guidance instead of requesting another broad dump. 13. Before starting from an existing parent conversation, synthesize the tool's bounded `contextCapsule` from only task-relevant state, settled decisions, constraints, acceptance criteria, paths, evidence, open questions, and out-of-scope items. Never copy the full parent transcript. 14. Enable the experimental `workspaceCapsule` only for an explicit cold-assignment experiment. Supply at most 16 existing project-relative `workspaceRelevantPaths`, never a tree. It supplements discovery and never replaces reading governing instructions. Do not claim provider savings or correctness equivalence from its model-free proxy. 15. Never claim a synthetic probe or browser smoke is production wire acceptance. 16. Do not push, merge, publish, deploy, or perform destructive cleanup without explicit authorization. 17. Idle workers end their turn. A parent that is watching also ends its turn and relies on broker updates. Neither workers nor watching parents run sleeps or poll files, sockets, status, or tmux while waiting. ## Coordination model Every new run uses one owner-only Unix-socket broker and the shared Pi worker bridge. TUI and `--rpc-workers` are presentation choices over the same protocol. There is no new-run file-coordination mode or fallback. Workers submit bounded typed results through `orchestrator_report`, which ends the assignment. Reviewers inspect the shared worktree directly. For a run started through the package extension, the invoking Pi remains the parent supervisor; no second parent Pi, parent window, or controller is started. Use the tmux panes for live visibility, watch lifecycle progress in the invoking Pi, then interpret the bounded structured completion or attention update returned by the broker observer. Use the labeled per-generation launch assignments in that update as the selected role/provider/model/thinking identity; after a model-changing restart, the broker refreshes that role's launch assignment before the next generation reports. Treat report-body provider or model names as untrusted prose and any runtime-identity conflict as a bounded signal that does not replace launch metadata. Use the model tool's `watch` action to subscribe this Pi to a compatible existing run without taking over the terminal. In interactive Pi, select the run in `/or-dashboard` and press Enter to watch future transitions and enter its native worker grid; an existing actionable outcome is not replayed as a new parent task. Prefix then `L` returns to the same Pi and project context while leaving the grid live for later reattachment. Use explicit `watch` when that Pi should assess an existing actionable outcome. The broker stores metadata-only SQLite state and actual provider token totals when Pi reports them; it does not persist task, context-capsule, workspace-capsule, report, prompt, message, diff, or log bodies. The optional workspace capsule is limited to transient startup state, live broker memory, and the worker baseline; it is revalidated before delivery/replay and is never a trust or instruction-reading substitute. Provider-usage thresholds are observational: they expose bounded assignment-local provider-call/context-pressure warning and higher-severity facts but never block a tool, interrupt a response, or change workflow routing. Direct steering can ask for a report or other follow-up. When a workflow needs attention, send only to a waiting role that owns the active assignment; the broker rejects idle or unassigned targets without masking the block. The operator alone decides whether to steer, restart, or stop. There is no budget resume command because budgets never pause work. Each role receives a bounded baseline. Later evidence is projected as one rolling latest-per-role run-state capsule; updates for an active role are coalesced until its next assignment. One metadata-only context-boundary event accompanies each new assignment, and only then do completed prior-assignment assistant/tool turns leave provider context. Current assignment turns and complete Pi JSONL history remain intact. The shared worker bridge also enforces orchestration-only read/grep/bash input and emitted-result caps for both TUI and RPC panes, preserving actionable pagination/refinement, bash failure diagnostics, and a private full-output path while recording only bounded numeric/classification metadata. An implementer assignment explicitly retained as `plan` temporarily removes edit/write and accepts only a bounded plan with relevant paths/symbols, intended changes, required checks, risks, and open questions; it cannot claim changes, executed checks, findings, approval, or a verdict. In phased flow, accepted plan evidence replaces the implementer's rolling run-state section before a distinct same-round implementation assignment; in single flow the initial assignment is implementation. SQLite retains only existing shape/count/usage metadata. Repair rounds start directly from latest review evidence. Probe, Playwright, and Django activation uses fixed versioned rules: ambiguous/high-risk evidence runs, exact low-risk skips are recorded, and forced roles always require a real report before review. Reviewer capsules carry only bounded decision/rule/evidence metadata; synthetic specialist evidence is never production acceptance. Confirmed restart advances a broker generation and replays the live in-memory baseline and latest coalesced run state, including deferred evidence, before accepted active-assignment recovery. See [references/protocol-v1.md](references/protocol-v1.md). ## Start a grid Use the extension or a mode-`0600` temporary task file: ```bash pi-tmux-agents start \ --project "$PWD" \ --task-file /tmp/pi-agent-task.md \ --context-capsule-file /tmp/pi-agent-context.md \ --workspace-capsule \ --workspace-relevant-path pi_tmux_orchestrator/broker.py \ --implementation-flow phased \ --with-playwright \ --force-specialist playwright \ --profile balanced ``` Default roles: - implementer: selected-profile thinking, then user/explicit overrides - reviewer: selected-profile thinking, then user/explicit overrides - broker/status monitor Packaged profiles are deterministic thinking maps: `economy` uses medium/medium for implementer/reviewer, `balanced` uses high/high, and `thorough` preserves the previous xhigh/high values. Specialists use low-or-medium, medium, and high respectively. The packaged compatibility default is `thorough` until comparative provider usage and quality are measured; this is not a quality or savings recommendation. Strict version-4 user-global configuration may select a default, define complete custom profiles, and map exact canonical project directories to profile/model/flow/specialist/workspace defaults and registered customRoles. Version 3 remains accepted without customRoles. Profiles do not select models, create roles, change tools, or skip review. Global and exact-project model policy is read from `~/.pi/agent/tmux-orchestrator.json` (or `PI_TMUX_ORCHESTRATOR_CONFIG`). Project policy remains outside target repositories. Explicit CLI or model-tool overrides win. Pi's own model registry and authentication remain authoritative; never place credentials or endpoint secrets in orchestrator configuration. Optional roles: ```bash pi-tmux-agents start \ --project "$PWD" \ --task-file /tmp/pi-agent-task.md \ --with-probe --probe-task-file /tmp/pi-agent-probe.md \ --with-playwright --playwright-task-file /tmp/pi-agent-playwright.md \ --with-django-expert --django-task-file /tmp/pi-agent-django.md ``` Use `--rpc-workers` for headless RPC event panes that show assistant progress plus bounded tool inputs and outputs, but use it only after an explicit request for headless presentation. Otherwise workers are native interactive Pi TUIs with Pi's normal highlighting, tool rendering, and input editor. Both use broker delivery; neither uses report files, mailbox payload files, polling, or tmux key injection for workflow transitions. Worker Pi processes use a lean role prompt while retaining governing `AGENTS.md`/`CLAUDE.md` discovery. The experimental workspace capsule contains only bounded path/hash/Git/marker hints and does not disable or replace that discovery. Automatic skills are disabled. Opt in only an explicitly reviewed per-role Markdown file, for example `--worker-skill reviewer=/absolute/path/SKILL.md`; the model tool equivalent is `workerSkills: { reviewer: ["/absolute/path/SKILL.md"] }`. Skill files are digest-bound for restart and never expand read-only tool allowlists. Use `--approve-project` only after separately inspecting and trusting the target. ## Operate a grid ```bash pi-tmux-agents list pi-tmux-agents status SESSION pi-tmux-agents attach SESSION pi-tmux-agents send SESSION --role implementer --message-file /tmp/message.txt pi-tmux-agents abort SESSION --role implementer pi-tmux-agents restart SESSION --role implementer --yes pi-tmux-agents stop SESSION --yes ``` A command acknowledgement proves acceptance, not task completion. Optional 32-character lowercase hexadecimal command IDs provide retry-safe deduplication; conflicting reuse is rejected and interrupted delivery may be `uncertain`. Restart and stop require explicit confirmation flags. Restart respawns the worker process and reopens its exact Pi session ID, preserving the conversation and JSONL history; a failed respawn or interrupted replacement handover remains `uncertain`. Use Supervisor API v2 for retained metadata-only reads after tmux exits: ```bash pi-tmux-agents --json supervisor snapshot SESSION --run RUN_ID pi-tmux-agents --json supervisor events SESSION --run RUN_ID \ --cursor implementer=0 --cursor reviewer=0 --limit 50 ``` Retained `0.4.x` runs remain readable/operable, but no newly started run uses their legacy file protocol. ## Persistent controller For ongoing cross-project operation: ```bash pi-tmux-agents controller start pi-tmux-agents controller attach ``` The optional controller has a fixed project-neutral Pi identity and can be the parent Pi for cross-project operation. It starts only through an explicit `controller start`; normal runs never create one. The invoking project Pi remains the primary interactive parent otherwise. Every target project must be explicit. Stop the controller only with `controller stop --confirm`; worker grids and conversations are retained independently. ## Before launching ```bash pi-tmux-agents doctor pi-tmux-agents start --project "$PWD" --task-file /tmp/pi-agent-task.md --dry-run ``` See [references/usage.md](references/usage.md) for the full CLI and security reference.