@jocax/agent-orchestrator0.2.0

@jocax/agent-orchestrator

Three multi-agent orchestration patterns in one package — background subagents with live widgets, dispatcher-only teams with grid dashboards, and sequential pipeline chains.

What

• Subagent Widget — Ad-hoc background subagents. Spawn subagents with /sub <task>, each running as an independent pi process. Live widgets show streaming output. Supports continuation (/subcont), removal (/subrm), and bulk clear (/subclear). Four LLM-callable tools let the agent programmatically create, continue, remove, and list subagents. This is the "delegate and monitor" pattern.

• Agent Team — Dispatcher-only orchestration. The primary agent is stripped of all codebase tools and given only a dispatch_agent tool. Teams are defined in .pi/agents/teams.yaml, individual agents in .pi/agents/<name>.md (pi custom agent format). A grid dashboard widget shows per-agent status cards with color-coded states. This is the "specialist dispatch" pattern.

• Agent Chain — Sequential pipeline. Chains are defined in .pi/agents/agent-chain.yaml as ordered steps, each specifying an agent and a prompt template. $INPUT carries the previous step's output forward, $ORIGINAL preserves the user's initial input. A pipeline card widget renders step flow with arrows. This is the "assembly line" pattern.

All three orchestrators compose without conflicts. Each is independently enabled via environment variables.

Why

Complex tasks need multiple agents with different specializations. Instead of one agent doing everything, these patterns let you:

• Delegate background work to subagents without blocking the main conversation
• Dispatch tasks to specialist agents through a dispatcher pattern
• Chain agents into sequential pipelines where each step builds on the previous

Install

Install the package from npm:

{
  "source": "npm:@jocax/agent-orchestrator"
}

Configuration

Each orchestrator is independently enabled via environment variables:

Variable	Default	Description
AE_PI_AGENT_ORCHESTRATOR_SUBAGENT	true	Enable the subagent widget orchestrator
AE_PI_AGENT_ORCHESTRATOR_TEAM	false	Enable the agent team dispatcher orchestrator
AE_PI_AGENT_ORCHESTRATOR_CHAIN	false	Enable the agent chain pipeline orchestrator

Set to false or 0 to disable, true or 1 to enable:

# Enable all three
AE_PI_AGENT_ORCHESTRATOR_SUBAGENT=true AE_PI_AGENT_ORCHESTRATOR_TEAM=true AE_PI_AGENT_ORCHESTRATOR_CHAIN=true pi

# Enable only agent chain
AE_PI_AGENT_ORCHESTRATOR_CHAIN=true pi

# Disable subagent (all others off by default)
AE_PI_AGENT_ORCHESTRATOR_SUBAGENT=false pi

Global Status

Check which orchestrators are active at any time:

/orchestrator status

Quick Start

Subagent Widget

Spawn background subagents and monitor them live:

/sub "analyze the src/ directory for performance issues"
/subcont 1 "now write tests for the issues found"
/subrm 1
/subclear

The agent can also manage subagents programmatically via LLM tools:

Tool	Description
subagent_create	Spawn a background subagent for a task
subagent_continue	Continue an existing subagent with a new task
subagent_remove	Kill and remove a subagent by ID
subagent_list	List all active subagents with status

Commands:

Command	Description
/sub <task>	Spawn a background subagent
/subcont <id> <task>	Continue subagent with new task
/subrm <id>	Kill and remove a subagent
/subclear	Kill and remove all subagents
/orchestrator status	Show which orchestrators are active

Agent Team

Define teams and dispatch tasks to specialist agents.

Commands:

Command	Description
/agents-team <name>	Select and activate an agent team (or off to deactivate)
/agents-list	List all available agents with their specializations
/agents-grid <N>	Set grid dashboard columns (1-6, default 3)

LLM Tool:

Tool	Description
dispatch_agent	Dispatch a task to a specialist agent (this is the ONLY tool when team is active)

Agent Chain

Select and run sequential pipeline chains.

Commands:

Command	Description
/chain <name> [input]	Select a chain (and optionally run with input)
/chain-list	List all available chains

LLM Tool:

Tool	Description
run_chain	Execute a named agent chain pipeline sequentially

Agent Format

Individual Agents — .pi/agents/<name>.md

Agents use pi's custom agent format with YAML frontmatter. Create a markdown file for each agent:

---
name: builder
description: Code writing specialist for TypeScript and React
tools: read write edit bash
model: claude-sonnet-4-20250514
thinking-level: high
---

# Builder Agent

You are a code writing specialist. Write clean, well-tested code.

Frontmatter fields:

Field	Required	Description
name	Yes	Agent name (matches filename without .md)
description	No	What this agent specializes in
tools	No	Space-delimited list of allowed tools (e.g., read write edit bash)
model	No	Model override for this agent
thinking-level	No	Thinking level override

Team Definition — .pi/agents/teams.yaml

Define teams as named groups of agents:

teams:
  - name: code-review
    description: Two-agent review workflow
    agents: [builder, reviewer]
  - name: full-cycle
    description: Build, test, review pipeline
    agents: [builder, tester, reviewer]

Each agent name must match a .pi/agents/<name>.md file.

Chain Definition — .pi/agents/agent-chain.yaml

Define chains as ordered pipelines of steps:

chains:
  - name: analyze-build-test
    description: Analyze codebase, build, then run tests
    steps:
      - agent: analyzer
        template: "Analyze this codebase and identify key modules: $ORIGINAL"
        description: Codebase analysis
      - agent: builder
        template: "Based on this analysis:\n$INPUT\n\nBuild the identified components. Original task: $ORIGINAL"
        description: Build components
      - agent: tester
        template: "Write tests for these built components:\n$INPUT\n\nOriginal request: $ORIGINAL"
        description: Write tests

Template variables:

Variable	Description
$INPUT	Output from the previous step (for step 1, equals $ORIGINAL)
$ORIGINAL	The user's original input, preserved across all steps

Examples

Run standalone demos for each orchestrator pattern:

# Subagent demo
pi -e software/packages/agent-orchestrator/examples/subagent.ts -p "/sub list files in src/"

# Agent team demo
pi -e software/packages/agent-orchestrator/examples/agent-team.ts -p "dispatch agent to builder"

# Agent chain demo
pi -e software/packages/agent-orchestrator/examples/agent-chain.ts -p "/chain analyze-build-test"

# All orchestrators stacked
pi -e software/packages/agent-orchestrator/examples/all.ts -p "/orchestrator status"

Run the demo

just demo agent-orchestrator ["Run the review chain" | "Dispatch to the team"]

A herdr workspace opens with pi, this extension and a disposable copy of the small-app sandbox. The demo sets AE_PI_AGENT_ORCHESTRATOR_CHAIN and _TEAM and seeds .pi/agents/teams.yaml, .pi/agents/agent-chain.yaml and two personas, so /chain and /agents-team exist from the first prompt.

Step	Do this	Watch
1	Type /chain-list	Available chains: review
2	Let the agent's task run, or type /chain review src/index.js yourself	the agent-chain-pipeline widget above the editor shows chain: review [builder done] → [reviewer done], then Chain "review" completed.
3	In the "Dispatch to the team" scenario, type /agents-team code-review	Team activated: code-review and a Team Dashboard widget appear
4	Type /agents-grid 2	the dashboard narrows to 2 columns
5	Send the scenario's follow-up prompt	dispatch_agent becomes the agent's only tool, and the dashboard tracks the builder and reviewer

/chain and /agents-team exist in this demo only because the kit sets AE_PI_AGENT_ORCHESTRATOR_CHAIN and _TEAM; in your own pi you must set them yourself.

Needs herdr 0.9.3 or newer and one reachable model provider — see demo-kit.

Development

# Type-check
npx tsc --noEmit -p software/packages/agent-orchestrator/tsconfig.json

# Run tests
npx vitest run software/packages/agent-orchestrator/tests/