pi-orchestration

Agnostic subagent orchestration for pi-coding-agent

A TypeScript package for orchestrating multi-agent workflows with depth limiting, worktree isolation, and model flexibility.

Features

• Single Execution: Spawn a single typed agent with a task
• Chain Execution: Execute agents in sequence, passing output between steps
• Parallel Execution: Execute multiple agents concurrently with limits
• Fork Execution: Share parent's context for efficiency

Agent Types

Type	Emoji	Purpose	Depth Limit
scout	🔍	Fast reconnaissance	0
specialist	🧠	Domain expert	1
worker	⚒️	Implementation	1
reviewer	👁️	Quality validation	0
coordinator	🎯	Task orchestration	∞

Model Flexibility

pi-orchestration inherits the parent agent's model registry and selects the best model for each agent type:

// "auto" = use parent's ctx.modelRegistry (default)
{ agent: "worker", model: "auto" }

// Explicit model
{ agent: "worker", model: "ollama/qwen2.5-coder:14b" }

// Use parent's current model
{ agent: "reviewer", model: "inherit" }

Supported Providers

• ollama/* - Local or cloud Ollama models
• claude/* - Anthropic Claude
• anthropic/* - Alias for claude/
• Any custom provider registered via pi-coding-agent

Installation

npm install @0xkobold/pi-orchestration

Usage

Single Execution

import { orchestrate } from "@0xkobold/pi-orchestration";

const result = await orchestrate({
  agent: "worker",
  task: "Implement user authentication",
}, ctx);

console.log(result.content);

Chain Execution

const result = await orchestrate({
  chain: [
    { agent: "scout", task: "Analyze the codebase structure" },
    { agent: "planner", task: "Create implementation plan" },
    { agent: "worker", task: "Implement the feature" },
    { agent: "reviewer", task: "Review the changes" },
  ],
}, ctx);

Parallel Execution

const result = await orchestrate({
  parallel: [
    { agent: "scout", task: "Audit frontend security" },
    { agent: "scout", task: "Audit backend security" },
    { agent: "scout", task: "Audit infrastructure" },
  ],
}, ctx);

With Options

const result = await orchestrate({
  agent: "worker",
  task: "Refactor authentication module",
  cwd: "/path/to/project",
  timeout: 60000,        // 60 second timeout
  maxOutput: 5000,       // 5000 character max output
  isolation: {
    type: "worktree",
    diffOnComplete: true,
    autoApply: false,
  },
  model: "ollama/qwen2.5-coder:14b",
}, ctx);

API

orchestrate(options, ctx)

Main orchestration function.

Options:

• agent - Agent type for single execution
• task - Task description
• chain - Array of steps for chain execution
• parallel - Array of tasks for parallel execution
• cwd - Working directory
• timeout - Timeout in milliseconds
• maxOutput - Maximum output length
• isolation - Isolation configuration
• model - Model override
• context - Context mode: fresh, fork, or inherit

Returns: OrchestrateResult | ChainResult | ParallelResult

Tools

• orchestrate - Main orchestration tool (single, chain, parallel execution)
• orchestrate_status - Check engine status and pi CLI availability

Architecture

src/
├── core/           # Types and agent definitions
├── utils/          # Model selection, depth tracking, templates
├── modes/          # Single, chain, parallel, fork execution
├── execution/      # Main orchestration engine
└── tools/          # pi-coding-agent skill definitions

License

MIT