Pi Tmux Orchestrator

A Pi package for coordinating coding agents in a monitorable tmux grid.

• One implementer writes and one independent reviewer is always required.
• Configure each orchestration's models, thinking profile, flow, budgets, skills, workspace hints, and optional built-in specialists.
• Native Pi workers remain visible and directly steerable in a grid that adapts to the roles enabled for that run.
• An event-driven broker handles structured coordination and recovery.
• Durable orchestration state is bounded and metadata-only.

Install

Requirements: Pi, Python 3.11+, tmux 3.2+, and macOS or Linux.

pi install npm:pi-tmux-orchestrator

Run once without installing:

pi -e npm:pi-tmux-orchestrator

Pi packages execute with your user permissions. Inspect packages before installing them.

Quick start

Start Pi inside tmux from the project you want to change:

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

Then use either:

/or-start Describe the change you want

or natural language:

Describe the change you want. Use the orchestrator.

Review the preview and confirm. The default run starts one implementer and the mandatory reviewer. No configuration file is required.

Open /or-dashboard to inspect or attach to runs. When attached to the worker grid, press the tmux prefix followed by L to return to the same Pi session.

Pi commands

The extension intentionally exposes only five commands:

Command	Purpose
/or-dashboard	List, inspect, attach/watch, run doctor, or confirm stop
/or-models [query]	Find exact provider/model IDs
/or-start [task]	Preview, confirm, and start work
/or-send [session]	Send private guidance; attention targets the waiting assignment, and post-ready implementer guidance opens a reviewed repair round
/or-stop [session]	Select and confirm stopping a run

The dashboard is keyboard-driven:

Key	Action
arrows or j/k	Select a run
Enter	Watch future transitions and attach
d	Run current-project doctor explicitly
r	Refresh the session list
x	Request confirmed stop
?	Show help
q or Escape	Close

Opening or refreshing the dashboard never runs doctor and never starts background polling. Attaching does not replay an already-completed outcome into the invoking Pi; use explicit watch behavior when that Pi should assess an existing outcome.

How it works

Tmux hosts the worker panes but does not transport workflow messages. Each run has an owner-only Unix-socket broker that authenticates role bridges, accepts bounded typed reports, and schedules the mandatory review.

The invoking Pi remains the parent supervisor. It receives event-driven completion or attention updates while each worker keeps its normal durable Pi session. The broker dashboard refreshes assignment-bound thinking, streaming, tool, reporting, and finalized-usage metadata directly from worker events; a NOW line shows who is working and who is waiting. It does not wait for handoff. Crashes and ambiguous delivery fail to uncertain rather than blindly replaying work.

The package supports interactive native Pi panes and explicit headless RPC workers through the same broker protocol. Ordinary new runs use manifest v5; explicit custom-role runs use v7. Both use broker-v1, and retained older runs remain readable.

Configure orchestrations

Every start can choose exact role models and thinking levels, a single or phased implementation flow, optional probe/Playwright/Django specialists, observational budgets, explicitly reviewed worker skills, and the experimental workspace capsule. Use /or-start, natural language, the model tool, or the terminal CLI; explicit run options take precedence.

For an opt-in repair cap, use /or-start's additional repair-round input, maxRepairRounds in the model tool, or CLI start --max-repair-rounds N. Blank/omission disables the cap; 0 pauses before the first repair. The run remains incomplete at the cap; explicit terminal CLI continue SESSION --yes --command-id <32-hex-id> authorizes one additional round. This does not limit an active assignment or change observational budgets. See continuation semantics.

For related worker investigation, use /or-start's worker-context input, tool workerContext: { reviewer: "retain" }, or CLI start --worker-context reviewer=retain. Other roles keep default pruning; mandatory review and run limits are unchanged. Retention can increase context cost. Retained roles receive bounded worktree-metadata reuse hints—not proof of current checks or permission to reuse approval. See context policy and reuse limitations.

Validate future custom-specialist definitions with pi-tmux-agents role-registry --project /absolute/project. This checks strict user-global definitions and reviewed resource digests; it does not launch custom roles. The shared bootstrap verifies pinned v6/v7 role/resource bindings and isolates read-only resources. Internal custom contract/routing/accounting checks and bounded control/presentation adapters are covered by model-free regressions. Isolated staged-package actual-Pi TUI/RPC startup, broker reconnection, restart, resource revocation, and cleanup are also covered without a prompt or provider request; this does not claim a generated custom report or provider behavior. Explicit CLI selection can be previewed with start --dry-run --custom-role ID PROVIDER MODEL THINKING (repeatable, at most eight). Version-4 exact-project customRoles can also select the same registered identities for one canonical directory; --no-project-custom-roles omits them, and explicit --custom-role wins. Provider/model values are always explicit. Thinking accepts an explicit level or profile to opt into the same identity's user-global custom-profile mapping; profile mappings never select workers and project profile selections cannot configure custom thinking. Selected roles use deterministic rules from their bound specialist contract, or --force-specialist CUSTOM_ID. Omit --dry-run to launch after model and resource validation. Retained custom status exposes contracts and bounded policy sources, not resource bodies or claims of current resource validity. See the registry, bootstrap, and workflow trust boundaries.

Reusable defaults are user-global, never project-local:

~/.pi/agent/tmux-orchestrator.json

Packaged profiles change only Pi thinking levels:

• economy
• balanced
• thorough — compatibility default

Profiles do not change models, tools, role authority, mandatory review, routing, or budget behavior.

Version-4 configuration can apply exact defaults to canonical project paths, including registered custom specialists. Version 3 remains accepted without customRoles:

{
  "version": 4,
  "defaultProfile": "balanced",
  "projects": [
    {
      "directory": "/absolute/canonical/path/from/pwd-P",
      "profile": "thorough",
      "implementationFlow": "phased",
      "specialists": ["probe"],
      "workspaceCapsule": false,
      "customRoles": [
        {
          "id": "custom-security",
          "provider": "exact-provider",
          "model": "exact-model",
          "thinking": "low"
        }
      ]
    }
  ]
}

Project directories must already exist and exactly match pwd -P; there are no globs, prefix matches, repository-name matches, or symlink components. Custom role IDs must already exist in the user-global registry. Explicit run options override an exact project mapping.

Pi remains authoritative for provider authentication. The orchestrator does not read or copy provider credentials. Model policy, custom profiles, specialist activation, observational budgets, worker skills, and workspace capsules are documented in the complete usage reference.

Upgrading to 0.10

Version 0.10.0 adds opt-in custom read-only specialists, worker-context retention, repair-round continuation, and a watchable broker dashboard. There is no new slash-command, protocol, or authority-model breaking change. The 0.9 command map below still applies.

Finish or stop active orchestrations, update, and restart Pi:

pi update npm:pi-tmux-orchestrator

Start a new orchestration after restarting. An already-running broker keeps the code loaded when that run started and does not hot-reload this release.

• Ordinary new runs still use manifest v5 and broker-v1. Explicit custom-role runs use manifest v7.
• Version-3 user-global configuration remains accepted without customRoles. Version 4 adds exact-project customRoles for already-registered identities.
• Retained older runs remain readable.
• Custom specialists, worker-context retention, and the repair-round cap are opt-in. Defaults do not start custom roles or retain extra worker context.

See the v0.10.0 release notes. If migration is blocked, stop active 0.10 runs and roll back:

pi remove npm:pi-tmux-orchestrator
pi install npm:pi-tmux-orchestrator@0.9.5

Upgrading to 0.9

Version 0.9 removed duplicate long-form commands and separate helper commands:

Before	Now
/orchestrator-dashboard	/or-dashboard
/orchestrator-models	/or-models
/orchestrator-start	/or-start
/orchestrator-send	/or-send
/orchestrator-stop	/or-stop
list/status/help/about/doctor/watch/attach helpers	/or-dashboard
supervisor/restart helpers	pi-tmux-agents or the model tool

Finish or stop active runs, update, and restart Pi:

pi update npm:pi-tmux-orchestrator

Existing manifest v1-v4 runs remain readable. The mandatory reviewer, one-writer policy, and thorough compatibility profile are unchanged.

See the v0.9.0 release notes and migration discussion archive. If migration is blocked, stop active 0.9 runs and roll back:

pi remove npm:pi-tmux-orchestrator
pi install npm:pi-tmux-orchestrator@0.8.1

Terminal CLI

The Python CLI provides the complete operational surface:

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 restart SESSION --role implementer --yes
pi-tmux-agents stop SESSION --yes

Run pi-tmux-agents --help for all commands, JSON output, Supervisor API, controller, profile, model, specialist, and headless-worker options.

Safety

• The implementer is the only writer; reviewer and specialist roles are read-only but are not OS sandboxes.
• Project trust, start, restart, and stop retain explicit confirmation boundaries.
• Existing tmux sessions are never replaced and operations use exact targets.
• Workflow, prompt, report, message, diff, log, provider, and credential bodies stay out of durable/public orchestration metadata.
• Provider usage and cost are shown only when Pi/provider metadata supplies them; synthetic benchmarks are not billing or quality claims.

See SECURITY.md for the complete security model.

Documentation

• Complete operator and CLI usage
• Custom read-only specialists
• Coordination protocol and state boundaries
• Dashboard design
• Pre-release artifact testing
• Changelog

Development

python -m pip install ruff==0.11.11
scripts/test.sh

The default test suite is model-free and isolates package, Pi, and npm state from real authentication. It also generates ephemeral measured JavaScript test coverage. To retain that report locally and run the same pinned health gate as CI:

scripts/test-coverage.sh
npx --yes fallow@3.22.0 health \
  --coverage .coverage/coverage-final.json \
  --baseline .fallow/health-baseline.json \
  --baseline-mode identity \
  --summary

The reporter converts Node's built-in test coverage event to Istanbul format. It is measured test execution evidence—not production runtime traffic—and Fallow reports how many JavaScript functions it matched before applying exact per-function CRAP scores. Unmatched functions remain explicit rather than being claimed as measured. Python tests remain authoritative regressions, but this repository does not claim measured Python coverage without a coverage tool.

Created and maintained by Revaz Zakalashvili. Licensed under the MIT License.