Pi Orchestrate

@zachwill/pi-orchestrate lets a Pi session delegate work to direct child sessions.

• Each worker gets a focused brief and a separate conversation.
• Workers run independently and return their results to the parent.
• Only the parent can delegate; workers cannot create more workers.

Requires Pi 0.85.0 or newer.

pi install npm:@zachwill/pi-orchestrate

The model

Each orchestrate dispatch creates a fresh worker session with its own transcript. The worker receives a complete brief from the parent but not the parent's conversation.

A worker definition is reusable configuration for the worker's prompt, tools, lifecycle, and optional model settings. The parent remains responsible for the user's complete requested outcome across its own and worker work.

Workers run in the background. orchestrate and interactive_send return acceptance so the parent can continue useful independent work, including tool calls dispatched alongside the workers. Worker dispatches in the same response form one result group; dispatches in later responses form separate groups.

Results return only to the parent session that started the workers. Results that settle while the parent is busy are queued. After the parent run ends normally, individual results can enter its context as they arrive; a dispatch group resumes the parent after every admitted member settles. The parent can do useful independent work before ending its run, or end promptly when progress needs worker evidence. A rejected, failed, or aborted worker does not cancel its peers; stopping other active workers requires an explicit worker_abort request.

Workers have one of two lifecycles:

• A one-shot worker returns one result and stops.
• An interactive worker returns a result and remains available for follow-up work.

A worker ID identifies a worker session. A run ID identifies one generation within it. An interactive follow-up creates a new run while preserving the worker ID and prior session context.

Interactive workers remain available across session switches and extension reloads within the same Pi process. Closing one releases its retained session; process shutdown releases any that remain.

Workers keep running when the parent conversation is compacted, and their results return automatically. Restarting Pi does not restore running workers.

Agent interface

Pi Orchestrate gives the parent five model-facing tools:

Tool	Purpose
orchestrate	Start a fresh worker with a title and complete brief
interactive_send	Continue an owned interactive worker that is ready
interactive_close	Release an owned interactive worker that is ready
worker_abort	Stop active workers owned by the parent
worker_status	Inspect the trusted catalog and diagnose the parent's worker state

The extension supplies the parent with instructions for using these tools.

Worker definitions

The package includes four fallback definitions in examples/workers/: scout for small factual probes, investigator for read-only cross-file research, worker for bounded implementation, and web for public web research. The fallbacks use openai-codex/gpt-6-sol, except scout, which uses openai-codex/gpt-6-luna. The web worker also requires an installed, authenticated Codex CLI.

Definitions are loaded by name in this precedence order:

1. Package fallbacks in examples/workers/
2. User definitions in ~/.pi/agent/pi-orchestrate/workers/*.md
3. Project definitions in <project>/.pi/pi-orchestrate/workers/*.md, when Pi trusts the project

A later definition replaces an earlier definition with the same name. Untrusted projects contribute no project definitions. Copy a fallback into a user or project directory to replace it.

A definition is a Markdown file whose basename matches its name:

---
name: reviewer
description: Reviews a bounded area and answers follow-up questions.
tools: read, grep, find, ls
lifecycle: interactive
---

Inspect only the assigned scope. Do not modify files. Return concise findings with file paths.

The frontmatter is strict:

Field	Meaning
name	Required definition name; must match the filename
description	Required catalog description used when choosing a worker
tools	Required nonempty tool list
lifecycle	one-shot or interactive; defaults to one-shot
model	Optional provider/model coordinate; omission inherits the parent's model
thinking	Optional thinking level: off, minimal, low, medium, high, xhigh, or max
skills	Optional exact skill allowlist; [] disables skills and omission uses normal discovery
compaction	Optional Pi compaction settings: enabled, reserveTokens, and keepRecentTokens

The Markdown body is the worker's nonempty system prompt. tools and skills accept either YAML arrays or comma-separated strings. Supported Pi tools are read, bash, edit, write, grep, find, and ls. Unknown fields and malformed definitions are rejected and appear in catalog diagnostics.

Trust boundary

Workers run in the parent process and are not security sandboxes. They share its filesystem and environment permissions.

Workers can use global Pi settings, authentication, packages, extensions, skills, and context. Trusted projects may add project-scoped resources. Untrusted projects do not contribute project workers, settings, extensions, skills, or context; global resources remain available.

A definition's tools field controls Pi's tool allowlist, not operating-system authority. A worker with bash can start external processes, including other agent CLIs. A read-only prompt also does not prevent writes when the worker has a write-capable tool.

Concurrent workers share the same working tree, so overlapping write scopes can collide.