$ cat ~/map/pi-tmux-orchestrator.md
pi-tmux-orchestrator
Pi extension + dependency-free Python CLI for coordinating implementer, reviewer, and optional probe agents in a monitorable tmux grid with a per-run Unix-socket broker.
tools✓ Oct 16
Facts
- repository
- github.com/revazi/pi-tmux-orchestrator ↗
- GitHub Stars
- ★ 2
- Forks
- 0
- license
- MIT
- npm / mo
- —
- last push
- Oct 12, 2026
install
pi install npm:pi-tmux-orchestrator## TL;DR
Pi extension, skill, and dependency-free Python CLI that coordinates coding agents in monitorable tmux grids — an implementer plus an independent reviewer, optional specialists, and a per-run Unix-socket broker with a live status dashboard.
## Key points
- $Grid roles: one implementer with normal Pi coding tools, one independent reviewer with read/verification tools, optional technical probe, Playwright tester, and Django expert — plus one event-driven, owner-only Unix-socket broker and adaptive status dashboard per run.
- $Short Pi command surface: /or-dashboard, /or-models, /or-start, /or-send, /or-stop. The /or-dashboard overlay (Ctrl+Shift+G) lists runs with workflow state, round, provider calls, tokens, cost, and context pressure; j/k navigate, Enter attaches, x stops, d runs doctor.
- $Worker model policy is configured per role in ~/.pi/agent/tmux-orchestrator.json — packaged thinking profiles economy/balanced/thorough, custom profiles, and per-project mappings; Pi's own provider auth and models.json stay authoritative and the orchestrator never reads credentials.
- $Event-driven coordination: no Markdown handoffs, readiness markers, mailbox payload files, relay polling, lifecycle sleeps, or tmux key injection; durable state is metadata-only SQLite plus complete Pi sessions under ~/.pi/agent/orchestrations/<session>/<run/>.
- $Also ships a versioned JSON CLI (pi-tmux-agents) and a tmux-independent Supervisor API v2, an optional persistent project-neutral controller session, and strict user-global budget thresholds in tmux-orchestrator-budgets.json.
- $Requirements: pi available as pi, Python 3.11+, tmux 3.2+ (3.5+ recommended), and Node 22.19+ for package verification.
## FAQ
Q Can I try it without installing it?
Yes — pi -e npm:pi-tmux-orchestrator runs it once without installation. For a reviewed install use pi install git:github.com/revazi/pi-tmux-orchestrator@<reviewed-full-commit>, or point pi install at a local checkout.
Q How do I watch a running orchestration?
Open /or-dashboard and press Enter to attach — the invoking Pi must be inside tmux. The tmux prefix followed by L detaches back to the same Pi while the run keeps running. From the terminal, pi-tmux-agents list/status/watch/attach do the same.
Q Where does the parent Pi fit in?
The Pi session that runs /or-start is the parent supervisor: it keeps an authenticated read-only broker observer, receives structured completion and attention reports, and decides next steps. Child Pi sessions never inherit parent project trust.
## References
## Related entries
$ pi-flows
Delegate work to isolated, budgeted pi sub-agents — recon, review, decomposition — with cost caps, OpenInference tracing, and contract validation.
$ pi-orchestrator
Strips the main agent down to a delegate tool that commands isolated, budgeted subagent workers.
$ aft
Sensorimotor-cortex layer that ships thin adapters for Pi and OpenCode, replacing raw read/write/edit/bash with semantic operations.
## Guides
Last updated: Aug 31, 2026