@mporenta/pi-cmux-orchestrator

A Pi package that lets a parent Pi session create and supervise visible, interactive Pi workers in cmux terminal surfaces. Workers remain human-observable and can be prompted, inspected, stopped, or handed over between the orchestrator and a person.

Requirements

• macOS with cmux installed and running
• cmux available on PATH
• pi available on PATH
• A Pi session launched inside cmux

Install

pi install npm:@mporenta/pi-cmux-orchestrator

For project-local installation:

pi install -l npm:@mporenta/pi-cmux-orchestrator

Try the package without installing it:

pi -e npm:@mporenta/pi-cmux-orchestrator

After installation, restart Pi. When developing from an auto-discovered extension directory, /reload reloads the extension.

First prompts to try

• “Spawn a Pi worker to review the current changes.”
• “List the Pi workers and show their ownership and liveness.”
• “Ask the worker to run the targeted tests, then report its latest result.”

Tools

| Tool | Purpose | |---|---| | spawn_pi_worker | Start a visible interactive Pi worker in the same or a new cmux workspace. | | send_worker_prompt | Send a follow-up or steering prompt to an orchestrator-owned worker. | | list_workers | List worker ownership, cmux surface, and liveness state. | | stop_worker | Gracefully stop a worker and optionally close its cmux surface. | | get_worker_result | Retrieve the worker's latest result. | | release_worker | Return a human-taken worker to orchestrator ownership. |

How it works

The parent extension starts a local Unix-domain socket server under the system temporary directory. It creates cmux terminal surfaces and launches child Pi processes in RPC mode with worker-specific environment variables. Workers connect back to the parent, exchange lifecycle events and prompts over the local socket, and stay visible in cmux.

A worker becomes human-owned when activity is detected directly in its terminal surface. The orchestrator will not prompt a human-owned worker until it is explicitly released.

Configuration

The extension configures workers internally through these environment variables; users normally do not need to set them:

• PI_CMUX_ORCH_ROLE
• PI_CMUX_ORCH_WORKER_ID
• PI_CMUX_ORCH_PARENT_SOCKET
• PI_CMUX_ORCH_RUN_DIR

Security and permissions

Pi packages run with the installing user's full system permissions. This extension:

• runs cmux commands to create, inspect, focus, and close terminal surfaces;
• starts local pi --mode rpc worker processes;
• sends text and key events to cmux surfaces;
• creates Unix sockets and transient runtime files under the system temporary directory;
• sends prompts and receives agent output over a local Unix socket;
• inherits the parent environment and therefore may expose available credentials to worker Pi processes.

It does not intentionally contact a remote service itself, but Pi workers may use configured model providers and tools. Review worker prompts and cmux surfaces before granting access to sensitive repositories or credentials.

Remove the package with:

pi remove npm:@mporenta/pi-cmux-orchestrator

Troubleshooting

• Not running in cmux: launch Pi from a cmux terminal surface.
• cmux or pi not found: ensure both executables are on PATH inherited by Pi.
• Worker does not come online: inspect its visible surface; startup waits are bounded and the surface may show an authentication or configuration error.
• Worker cannot be prompted: check list_workers; release it if ownership was transferred to a human.

Development

npm install
npm run typecheck
npm run pack:dry-run
pi -e ./index.ts

License

MIT