@groeponline/pi-agent-orchestrator

What it is

Pi Agent Orchestrator is the execution layer for workflows that need more than one agent. It runs inside the Pi host process and adds lifecycle control, permission inheritance, optional worktree isolation, scheduling, handoffs, orchestration modes and an interactive operator surface.

It does not require a package-owned backend. Optional telemetry is inert until an operator explicitly configures it.

Need	Orchestrator capability
Explore a codebase in parallel	Bounded read-only Explore agents
Plan before changing code	Read-only Plan agents
Implement without colliding with other work	General-purpose agents with optional git worktrees
Coordinate several agents	Groups, crews, swarms and structured handoffs
Keep recurring work visible	Persistent schedules plus daemon view
Intervene while work is running	/agents dashboard, steering, selection and termination
Carry evidence between agents	Machine-readable handoff payloads

Install

Global Pi install:

pi install npm:@groeponline/pi-agent-orchestrator

Try it for one session without changing your Pi settings:

pi -e npm:@groeponline/pi-agent-orchestrator

Project-local install:

pi install npm:@groeponline/pi-agent-orchestrator -l

The extension runs inside the Pi host process and does not require a package-owned hosted control plane or data service. In-process telemetry stays local (src/telemetry.ts); there is no package-owned PostHog or OpenTelemetry backend.

For installation, the first-run mental model and safe operating patterns, see Getting started. (chore(release): v0.19.1)

First useful run

Start with the packaged audit workflow:

/orchestra-audit src

Then open the live control surface:

/agents

The audit fans out read-only work, collects evidence and synthesizes the result. The dashboard lets you inspect running and queued agents while that work is active.

Common dashboard controls:

Key	Action
j / k or arrows	Navigate
Space	Multi-select
t	Resource top view
z	Daemon schedules
Shift+K	Terminate selected agents
?	Help
/perf	Performance metrics

For installation, the first-run mental model and safe operating patterns, see Getting started.

How orchestration works

operator / workflow
       │
       ▼
 orchestration dispatch
       │
       ├── Explore / Plan ───── read-only evidence
       ├── Analysis ─────────── optional ctx_* sandbox
       └── general-purpose ─── bounded implementation
                   │
                   ▼
        permissions + budgets
        + optional worktree
                   │
                   ▼
          structured handoff
                   │
          ┌────────┴────────┐
          ▼                 ▼
      next agent       parent/operator
          │                 │
          └────────┬────────┘
                   ▼
            `/agents` view

The default orchestration mode is single; multi-agent dispatch is opt-in. Internally the dispatcher supports single, crew, swarm and auto strategies. Child agents can only become more restricted than their parent: inherited tool restrictions, partition filters, explicit disallow rules, budgets and depth limits are resolved before execution.

See Architecture, Execution strategies and Tool calling for the detailed contracts.

Core capabilities

• Interactive TUI dashboard — agent list, resource top, daemon schedules, performance metrics, help, and settings.
• Subagent lifecycle — spawn, queue, steer, stop, inspect, and collect structured results.
• Permission inheritance — children cannot silently regain tools or scopes removed by a parent.
• Worktree isolation — optional branch and filesystem isolation for implementation agents.
• Prompt compression profiles — static system-prompt guidance with global defaults and per-agent overrides; this does not compact conversation history.
• Persistent scheduling — cron, interval, and one-shot jobs with a daemon schedule view.
• Structured handoffs — machine-readable transfer between agents and chained workflows.
• Swarm coordination — dynamic membership and coordinated completion.
• Cross-extension RPC — per-process capability-token authentication for peer extensions, mutation rate limits, and a strict spawn-option allowlist. See Cross-extension RPC.

Built-in agent types

Type	Mode	Use when
Explore	read-only	Parallel codebase discovery and evidence collection
Plan	read-only	Architecture and implementation planning before edits
Analysis	read-only + ctx_*	Sandboxed data or compute through optional @groeponline/context-mode
general-purpose	full tools	Bounded implementation and multi-step execution

Project-specific agents live in .pi/agents/*.md. Their frontmatter can define tools, models, limits and behavior. See Custom agents.

Isolation and safety model

The orchestrator treats execution boundaries as data, not prompt convention:

• parent tool restrictions are inherited by children;
• partition filters and explicit disallow rules reduce the available toolset;
• depth, turn and budget limits bound autonomous execution;
• implementation agents can use git worktrees for filesystem and branch isolation;
• structured handoffs keep transfer state explicit instead of relying on hidden conversation context;
• interactive logging stays quiet by default so terminal UI is not corrupted;
• cross-extension RPC uses capability-token authentication, a strict spawn-option allowlist and mutation rate limits.

The package does not automatically merge, publish, tag or deploy unless such actions are explicitly part of the requested workflow.

Operator surface

/agents is the live control plane for the current Pi process. It exposes agent state, queue state, resource usage, schedules, health information and lifecycle actions. The footer status slot can also show running and queued counts without opening the full dashboard.

The visual showcase is rendered from real product renderers rather than a mock UI:

• Product film
• Dashboard preview
• Agent-readable project site
• Showcase media layout

Packaged skills and workflows

The npm package includes progressive-disclosure skills and ready-made orchestration templates.

Entry point	Purpose
/skill:pi-orchestra	Evidence-first orchestration operating model
/skill:pi-typescript-extension-engineering	Strict Pi extension engineering and review
/skill:real-product-showcase	Real terminal/browser/app capture and media verification
/orchestra-audit [scope]	Parallel read-only audit and ranked synthesis
/orchestra-plan <goal>	Evidence gathering followed by a mechanically verifiable plan
/orchestra-implement <goal>	Discover, plan, implement in one isolated writer and independently verify

Install individual Agent Skills into another compatible client:

npx skills add https://github.com/GroepOnline/pi-agent-orchestrator --skill real-product-showcase
npx skills add https://github.com/GroepOnline/pi-agent-orchestrator --skill pi-typescript-extension-engineering

Where it fits

The GroepOnline Pi stack deliberately separates capture, durable state and execution:

Stage	Package	Owns
Capture	pi-wishcraft	Operator cockpit and lightweight ideas
Persist	pi-missions	Durable plan, queue, evidence, recovery and mission handoff state
Execute	pi-agent-orchestrator	Agents, worktrees, swarms, schedules and execution handoffs

A common flow is idea → mission → orchestration run, but the Orchestrator also works standalone.

Documentation

Start at the documentation index. The main paths are:

• Getting started — installation, first run and operating model.
• Architecture — topology, permission flow, lifecycle and module map.
• Tool calling — execution lifecycle, cancellation, concurrency and result ownership.
• API reference — tools, settings, handoffs and scheduler.
• Custom agents — agent frontmatter and examples.
• Execution strategies — single, crew, swarm and auto dispatch.
• Prompt compression — prompt profile scope and behavior.
• Performance — budgets, benchmarks and profiling.
• Troubleshooting — diagnostics and common operator fixes.
• v0.19.1 release notes — exact patch scope and demo hardening.

Contributor and policy references: AGENTS.md, CONTRIBUTING.md, SECURITY.md, ROADMAP.md and CHANGELOG.md.

v0.19.1

v0.19.1 publishes the reviewed 0.19 runtime state and adds the bounded Explore handoff demo path, deterministic handoff parsing checks and hardened recording preflight. The demo verifies its live model route before capture and does not mutate global Pi trust. See the full release note.

Development

npm ci
npm run setup:hooks   # optional local hooks
npm run typecheck
npm run lint
npm test
npm run build
npm run verify:package

Cursor Cloud users can run the canonical repository gate:

npm run verify:cloud
npm run cloud:smoke

The deterministic cloud environment pins the repository Node version and includes Chrome plus the Pi host CLI for smoke testing without a model API key.

License

MIT © GroepOnline