ORCH Agents Extension

CMUX-native peer-to-peer Pi agent communication.

This is not an orchestrator/sub-agent extension. Every Pi instance that loads the extension is an independent peer in the current CMUX workspace. Peers can discover each other, keep persistent logical connections, message each other, wait for replies, and spawn missing peers as visible CMUX splits.

Install / run

From npm

After publishing:

pi install npm:@aryanbhargav/pi-orch-cmux

Or try it for one session without installing:

pi -e npm:@aryanbhargav/pi-orch-cmux

If your npm scope is different, change the name field in package.json before publishing.

From a local checkout

From this directory:

pi -e extensions/orch-cmux.ts

Or install the local package into Pi from inside this directory:

pi install .

From the parent repo root, use:

pi install ./ORCH-Agents-extension

Named peer example:

pi -e extensions/orch-cmux.ts \
  --orch-name planner \
  --orch-role planner \
  --orch-purpose "Plans work and asks peers for implementation/review help"

Mental model

planner  ↔  coder
   ↕          ↕
reviewer ↔  tester

Not:

orchestrator
  ├── coder
  └── reviewer

The first/default agent can bootstrap the mesh, but it does not own the other agents.

Transport

No HTTP/SSE server. No Bun hub. No sockets.

The extension uses:

• CMUX identity: workspace, pane, and surface refs
• CMUX split creation for visible peer spawning
• Local mailbox files for reliable prompt/response exchange
• Background registry heartbeat for persistent peer connections

Default state directory:

~/.pi/orch-cmux/workspaces/<workspace-key>/
  peers/                 # live peer registry
  inbox/<session-id>/    # inbound prompt envelopes
  responses/<session-id>/# response envelopes

Footer

The extension replaces Pi's default footer with a compact ORCH footer:

@coder · gpt-5.5 · think:high                       [#####-------] 42%

Spawned peers display their own @name because orch_spawn_peer launches them with --orch-name, --orch-role, and --orch-purpose.

Tools

orch_peers

Diagnostics view of connected peers. The model should not call this before every send because orch_send uses the persistent peer cache internally.

orch_spawn_peer

Creates a CMUX split and launches another Pi peer with this same extension.

If model is omitted, ORCH uses the configured model default for that peer's role/name. If no default exists and Pi is interactive, ORCH asks which model to use. In non-interactive mode, it falls back to the current model.

Example target shape:

{
  "name": "coder",
  "role": "coder",
  "purpose": "Writes code",
  "direction": "right"
}

orch_send

Sends a task/prompt to a peer.

If the peer is missing and you want it created, set:

{
  "create_if_missing": true
}

Optional:

{
  "await_response": true
}

orch_get

Non-blocking poll for a response by msg_id.

orch_await

Block until the response arrives or the timeout fires.

Footer UI

ORCH replaces Pi's default footer with a compact CMUX-style status line:

• left side: model name, thinking level, and context usage, e.g. gpt-5.5 · think:xhigh · 12.4k/200k 6%
• default/main agent badge: live peer count, e.g. 3 live agents
• spawned peer badge: peer identity, e.g. @coder

The old expanded mesh widget is hidden by default to keep the editor clean. If you want it back for debugging:

ORCH_CMUX_SHOW_PEER_WIDGET=1 pi -e npm:@aryanbhargav/pi-orch-cmux

Slash commands

/orch

Status and diagnostics:

/orch
/orch refresh
/orch whoami

/orch-model-default

Configure default models for spawned peer roles/names:

/orch-model-default
/orch-model-default list
/orch-model-default set coder deepseek/deepseek-v4-pro
/orch-model-default set reviewer kimi/kimi-k2.6
/orch-model-default set planner openai-codex/gpt-5.5
/orch-model-default clear coder

Defaults are stored at:

~/.pi/orch-cmux/model-defaults.json

Lookup order when spawning is:

1. explicit model argument
2. role default, e.g. coder
3. name default, e.g. CodingRiver
4. wildcard default *
5. interactive prompt
6. current model fallback in non-interactive mode

Flags

All flags are namespaced to avoid extension collisions:

| Flag | Description | | --- | --- | | --orch-name | Peer name. Defaults to default with collision suffixing. | | --orch-role | Role/persona, e.g. planner, coder, reviewer. | | --orch-purpose | Human-readable purpose. | | --orch-project | Registry namespace. Defaults to current CMUX workspace. | | --orch-color | Hex color for widgets. | | --orch-explicit | Hide from broad discovery; exact addressing still works. |

Example workflow

User tells the default peer:

Send this task to coder agent: implement the login form.

Expected tool flow:

orch_send target="coder" create_if_missing=true prompt="Implement the login form..."

If no coder exists, the extension:

1. Checks the configured model default for coder; if none exists, asks which model to use.
2. Creates a new CMUX split with focus disabled.
3. Launches Pi in that split with --orch-name coder.
4. Waits for coder to register.
5. Sends the prompt to coder through the local mailbox.
6. coder receives an ORCH inbound message and replies normally.
7. coder's final assistant message is automatically written back as the response.
8. The sender can use orch_await/orch_get, or orch_send can wait directly with await_response=true.

Safety / loop rules

• Inbound messages tell the receiving agent to reply normally.
• The receiver should not call orch_send back to the original sender as a reply.
• The extension auto-returns the final assistant message at agent_end.
• orch_send increments hop count when forwarding from an inbound turn.
• ORCH_CMUX_MAX_HOPS defaults to 5 to limit ping-pong chains.

Publishing

This directory is a Pi package. The package manifest is in package.json:

{
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions/orch-cmux.ts"]
  }
}

Before publishing:

cd ORCH-Agents-extension
npm run check
npm pack --dry-run
npm publish

For a scoped package, publishConfig.access is already set to public.

Environment variables

| Variable | Default | Purpose | | --- | --- | --- | | ORCH_CMUX_DIR | ~/.pi/orch-cmux | Registry/mailbox root. | | ORCH_CMUX_HEARTBEAT_MS | 10000 | Peer heartbeat interval. | | ORCH_CMUX_REFRESH_MS | 3000 | Peer cache refresh interval. | | ORCH_CMUX_INBOX_SCAN_MS | 1000 | Inbox polling interval. | | ORCH_CMUX_TIMEOUT_MS | 1800000 | Default await timeout. | | ORCH_CMUX_MAX_HOPS | 5 | Forwarding hop limit. |