Pi Tmux Orchestrator

Coordinate coding agents in visible tmux panes from Pi. Each run has one implementer and a mandatory independent reviewer, with structured broker coordination and durable metadata-only state.

Install

Requirements: Pi, Python 3.11+, tmux 3.2+, macOS or Linux. Ordinary worker adapters have a Pi 0.87.1 compatibility baseline; opt-in enforcing provider-call ceilings require exactly Pi 1.4.0 and the reviewed OpenAI SSE adapters.

pi install npm:pi-tmux-orchestrator

Try without installation: pi -e npm:pi-tmux-orchestrator. Packages run with your user permissions; inspect before installing.

Quick start

Start Pi in tmux, from the project to change:

tmux new -s coding
cd /absolute/path/to/project
pi

Then run /or-start Describe the change or ask naturally to use the orchestrator. Review the preview and confirm. Defaults need no configuration. Use /or-dashboard to inspect runs; when attached, press tmux prefix then L to return to Pi.

Commands

The dashboard supports arrows or j/k, Enter to attach/watch, d for doctor, r to refresh, x for confirmed stop, ? for help, and q/Escape to close. Opening it does not run doctor or poll in the background.

Model-tool recovery

The bounded tmux_orchestrator tool also supports exact-session stop and exact-role restart/abort, through the authoritative CLI and broker. Stop and restart each ask for separate interactive TUI or RPC confirmation tied to the selected run; project trust or a prior start approval cannot authorize them. Abort requests cancellation, not completion. A restart acknowledgement is not a completed handover or completed task; duplicate restart retries never respawn again and report uncertain completion. After inspecting a stuck handover, request a fresh restart with a new command ID and separate confirmation; an uncertain role state does not block recovery. Abort still requires a connected worker, and restart still requires the broker's live in-memory baseline and resource checks.

Start may supply an exact session (1–128 ASCII letters, digits, _, ., -; ./.. are reserved). A collision returns metadata-only data.collision: exact session, safely available retained workflow/role states, and valid next actions. Inspect status, attach in a tmux TUI, separately confirm stop, or explicitly choose another start session. Ordinary non-orchestrator sessions cannot be stopped through this tool. Nothing automatically stops, replaces, renames, or reuses existing work.

Controls accept optional exact run and 32-character lowercase hexadecimal commandId. Keep both when retrying an uncertain command; stop/restart bind the confirmed run automatically. A confirmed same-ID stop retry can reconcile an interrupted receipt: it stops only the original live run, or completes after a successful observation that the session is absent. Concurrent retries fail uncertain without waiting. A completed stop receipt can be replayed after retention without killing a new same-name session; unavailable observations and replacement sessions never authorize a kill or claim completion. Retained state is never proof of a live broker. The five slash commands are unchanged. See recovery usage and compatibility.

Safety and configuration

Tmux hosts panes; an authenticated local broker transports typed workflow reports. Ambiguous delivery fails closed rather than blindly replaying work. Worker prompts and project payloads are not retained in broker metadata. Stop and start actions require confirmation; review authority cannot be removed.

Workers may end a blocked assignment with typed orchestrator_attention (clarification, blocked, tool_failure, or report_failure). Optional summary and question are bounded, live-parent UI-only, never stored or replayed. Parent updates retain only assignment/attempt/settlement metadata. An unreported settlement gets one private system reminder and at most one extra provider request; a second settlement becomes actionable needs_attention. Reconnect or restart never renews that allowance. Acknowledgement or a reminder is not task completion; only an accepted final report satisfies the assignment. Send follow-up only to the waiting role owning it. Explicit resume authority survives reconnect/restart separately from the consumed automatic allowance. See the protocol.

Runs can select exact role models and thinking, single/phased flow, optional built-in specialists, budgets, reviewed skills, and worker-context policy. Static starts additionally support explicitly confirmed enforcing provider-call ceilings, with broker-coordinated admission and operator-only allowance extensions; actual-cost enforcement remains unavailable. Model-guided planning is opt-in and separately confirmed. Details and strict user-global configuration examples are in the usage guide; protocol and custom specialist details are in protocol and custom roles.

Upgrade to 0.12.0

Version 0.12.0 adds worker attention/recovery, independently scoped dynamic planning, task-intent admission, auditable accepted-plan evidence, and optional static provider-call ceilings. Ordinary static starts and the five slash commands keep their existing defaults. Existing 0.11.1 approved pools and supported external configuration versions remain valid; there is no mandatory configuration rewrite. Dynamic planning now rejects unsupported provider-composition claims and oversized request/evidence projections before launch. Generate a fresh preview rather than reusing an older accepted plan. See 0.12.0 release and migration notes for the exact enforcement boundary, limitations, and rollback.

Users upgrading from before 0.11.1 still need operator-approved exact worker models for opt-in dynamic planning (the pool migration below). Finish or stop active runs and preserve your external configuration before replacing the package. Choose a migration below, then update with pi update npm:pi-tmux-orchestrator (or reinstall with pi install npm:pi-tmux-orchestrator) and restart Pi. Open /or-dashboard, use d for an explicit configuration check, and generate a fresh planning preview before confirming a new dynamic run. Existing retained runs remain readable; never resume an in-flight run across versions.

Task intent: orchestration or a direct parent answer?

Supply operator intent through model-tool taskIntent, terminal --task-intent, or the /or-start intent selector: change, investigation, review, or advisory (exact lowercase values). Use change when repository implementation needs a writer and independent review. For explanations, investigation, or a review without edits, the parent can usually answer directly.

This is Stage 1 admission, not a new advisory workflow or chat router. Explicit non-change intent offers direct-parent redirection or cancellation in Pi; the CLI returns a clear direct-parent notice. Neither option creates tmux, broker, worker, manifest, or worker provider calls. Even --dynamic-plan --yes cannot convert non-change work into implementation; a fresh explicit change request is required. No task is automatically sent back as a new parent turn.

Omitting intent preserves ordinary static change starts without classification. The one authorized dynamic-planning call also recommends a bounded intent; that recommendation is previewed, digest-bound, and subordinate to explicit operator intent. With omitted intent, a non-change recommendation redirects or cancels rather than launching. With explicit change, a conflicting recommendation remains visible in the final launch confirmation. Launched work retains one writer and mandatory review; phased inspect/plan is still a precursor to implementation, not an investigation-only workflow. Only bounded intent metadata is retained, never task, rationale, or provider bodies.

Single-provider support admission

When the final eligible roster admits both compositions, a homogeneous dynamic assignment requires single_provider and one bounded provider_support Choice claiming a material task-specific canonical capability or declared-cost advantage across every selected role. The same confirmed TypeSafe request (or equivalent Pi JSON) carries this selector, not free-form rationale. A model-free gate derives and binds exact selected/alternative facts; neutral, missing, unsupported, ambiguous, name-based, or cross-role-inapplicable support fails before preview or tmux/broker/worker launch. Mixed assignments must agree with composition (mixed or neutral); no mixed-is-better claim is made.

Exact locks or genuinely single-provider eligibility that leave only one final composition are derived locked/fixed, not planner-justified. No support call, retry, fallback, or plan substitution occurs. Revise constraints, use exact overrides, explicitly choose static/manual planning, or cancel. See the bounded support contract for conservative materiality rules. Historical v1–v6 reads/authority remain intact; new v7/evidence-v3 records require support metadata and revalidate catalog facts at final confirmation. Static defaults remain unchanged.

Auditable accepted-plan evidence

Dynamic planning remains opt-in. Rectangular unlocked catalogs keep planning v7 / evidence v3 and independent model_ / thinking_ Choices. When both model and thinking are unlocked and support is not a rectangle, the same one call asks one tuple_ Choice over exactly the eligible pairs. That accepted record is planning v8 / evidence v4: the tuple axis is the joint Choice, not a synthesized conditional probability and not a calibrated outcome probability. Rectangular roles in the same record keep independent axes. v7 records are not reinterpreted as joint confidence.

Direct TypeSafe and Pi share that request. Each Choice has at most 255 options and each request at most 255 questions. 255 is the generic TypeSafe Choice cap. The currently reachable approved-pool ceiling is 224 eligible pairs: 32 identities times the seven current thinking levels. That full product is rectangular, so it stays independent model_ / thinking_ Choices. Joint tuple_ is only a non-rectangle, so the largest approved-pool tuple Choice is 223 options, not 224. The wrapped request is at most 96 KiB. Retained evidence is at most 224 KiB; that byte cap is not the pair ceiling. Approved pools remain 1–32 identities per pool and 100 distinct identities overall; current worker thinking policy is unchanged. Capability objects stay one canonical, redacted, digest-bound copy. If the canonical JSON exceeds 96 KiB, planning rebuilds it once locally as compact-v1 (composition candidates become catalog indexes; fact digests are not repeated) and sends that only if it still fits. compact-v1 is a local encoding, not production wire acceptance. If the request cannot fit, or the measured upper bound of reachable retained evidence cannot fit in 224 KiB, planning fails before HTTP. That bound covers maximum-width Choice probabilities and the largest derived support object across common providers, references, and optional-role omissions. It is not a flat pad and does not drop tuples. That evidence failure is legitimate for some five-role joint pools and some legal multi-provider pools even when every Choice is within 255 options and a one-hot answer would fit. There is no retry, silent tuple omission, or provider-backed cost or quality claim. Planning v5–v8 manifests use the 1 MiB ceiling; older manifest limits are unchanged.

Fresh rectangular planning v7 records retain evidence v3: selected Choice confidence and probability, plus up to three alternatives for roster, independent per-role model/thinking axes, task-intent recommendation, and locked-plan suitability when that question exists. Options bind exact canonical identities to the same supplied non-secret capabilities and declared catalog cost hints. These are planner signals, not hidden reasoning, joint confidence, measured spend, quality, reliability, or cost-savings evidence.

Fixed/locked or single-option axes have deterministic fixed authority and no probabilities. Pi fallback choices explicitly have unavailable probabilities; static and planning v1–v4 reads explicitly report unavailable evidence. Homogeneous and mixed provider plans expose rationale_unavailable, never invented Jev reasoning. Planning v5/evidence v1 remains readable with its existing axes but provider-composition decision authority unavailable. Immutable launch assignments remain authoritative.

The same one authorized call asks one run-wide provider_composition Choice: single_provider, mixed_provider, or no_material_preference, only when both single and mixed assignments are feasible after role-specific eligibility, thinking/model locks, mandatory roles, and optional/trusted custom inclusion. A unique composition is fixed by those constraints, with no planner confidence. Single requires exactly one assigned provider; mixed requires at least two; neutral permits mixed only when both compositions remain feasible. Both TypeSafe and Pi fallback enforce this jointly with the final included roster/tuples before preview. Wording is provider/model-name neutral and permits only supplied canonical capabilities, declared catalog cost hints, task/context constraints, role contracts, and locks—not inferred quality, reliability, recency, latency, billing, or a claim that diversity improves outcomes. Canonical feasible-option facts and selected composition are digest-bound and visible in exact evidence and bounded summaries. The single-provider support gate above adds bounded same-call applicability and derived comparisons without an extra call, composition knob, or default change. Unsupported plans return bounded recovery guidance across model-tool, slash/TUI, and terminal/RPC starts.

Exact preview/confirmation, reopened planning, JSON/human status, Supervisor snapshots, dashboard summaries, and parent final evidence expose this bounded projection. Collection reads use digest-bound summaries; exact status/snapshot reads contain the catalog and alternatives. Strict validation rejects malformed, non-normalized, duplicate, oversized, stale, and fact-mismatched evidence before launch. No task/context/guidance, credentials, endpoints, response/error bodies, or hidden reasoning are retained. See the evidence contract. No default rollout or live-provider acceptance is implied.

Approved worker pools for dynamic planning

Dynamic planning axes are independently selectable with model-tool planningScopes: ["topology", "models", "thinking"], repeatable terminal --planning-scope, or /or-start --plan-scopes (seven-choice TUI form). For example, planningScopes: ["topology"] locks worker identities and thinking to effective per-run/project/global/profile policy. Omission preserves explicit dynamicPlan=true all-axis behavior; static defaults are unchanged. The one preflight call and final launch confirmation remain separate. See independent scopes.

Dynamic starts (/or-start --plan, dynamicPlan=true, or terminal --dynamic-plan) no longer offer the full available catalog. Before upgrading, finish active runs; then configure exact operator-approved worker identities in external ~/.pi/agent/tmux-orchestrator.json (or the absolute PI_TMUX_ORCHESTRATOR_CONFIG path). Preserve existing fields, change the root version to 5, and add workerCandidates: {"version":1,"all":[{"provider":"provider-a","model":"exact-worker-a"}]}. Optional built-in roles pools replace all for that role. Pools have 1–32 identities each, at most five role pools and 100 distinct identities total. Choose exact IDs from /or-models, not model-name quality or recency heuristics.

Exact run/project/global role locks override pools; custom roles keep fixed bindings. Fully locked alternative: keep configuration versions 1–4 without a pool and supply exact authoritative provider/model locks for every planner-eligible role, including optional roles the planner might select; explicitly disable optional roles you do not lock. Thinking-only settings and packaged defaults are not exact locks. Otherwise planning fails before a provider call with configuration guidance; it never silently falls back to the catalog. Both TypeSafe Jev and Pi fallback use the same approved scope and canonical capabilities. Confirmation and the immediate start acknowledgement show pool source/count and exact selected assignments, not configuration bodies. Ordinary static starts and configuration versions 1–4 remain supported. Planning v1 is read-only; existing v2–v6 admission remains compatible, while fresh dynamic previews use v7 or v8 according to the eligible model/thinking shape. Older records remain readable: v1–v4 evidence is unavailable; v5 evidence lacks explicit provider-composition decision authority. See approved-pool configuration and migration and provider-free acceptance.

Command map and rollback

The five commands are unchanged from 0.11.0. For older installations:

See the authoritative 0.12.0 release and migration notes and the intended GitHub Release. Release announcement #217 records migration guidance and notice timing. The earlier approved-pool migration is archived in announcement #202. If migration is blocked, finish or stop active runs, run pi remove npm:pi-tmux-orchestrator, then pi install npm:pi-tmux-orchestrator@0.11.1 and restart Pi. Preserve the original installation until in-flight runs are safely finished or stopped; do not resume them across versions. See rollback steps and the prior 0.11.1 release notes.

Help and documentation

• Detailed usage and configuration
• Prerelease testing
• Dashboard design
• Security policy
• Changelog
• Support and bug reports