pi-spawn

Spawn headless pi agents in parallel, collect their output. The shared substrate for multi-agent pi tools (council, review-council, etc).

Install

npm install @bytes032/pi-spawn

Usage

import { spawnAgents } from '@bytes032/pi-spawn';

const agents = [
  { name: 'claude', provider: 'anthropic', model: 'claude-opus-4-6', flags: '--thinking high' },
  { name: 'gpt', provider: 'openai', model: 'gpt-5.3' },
];

const results = await spawnAgents(agents, 'Review this code for bugs.', {
  piFlags: '--tools read,grep,find,ls',
  timeout: 600,
});

for (const result of results) {
  if (result.error) {
    console.error(`${result.name} failed: ${result.error}`);
  } else {
    console.log(`${result.name}: ${result.text}`);
    // result.sessionId can be passed back for session continuity
  }
}

Session Continuity

Pass sessionId back to agents for multi-round conversations:

// Round 1
const round1 = await spawnAgents(agents, 'Review the diff.');

// Round 2 — agents remember round 1
const agentsWithSessions = agents.map((a, i) => ({
  ...a,
  sessionId: round1[i]?.sessionId,
}));
const round2 = await spawnAgents(agentsWithSessions, 'Re-check after fixes.');

Custom Commands

Override the auto-built pi command with explicit start/continue:

const agents = [
  {
    name: 'custom',
    start: 'pi --mode json --provider anthropic --model claude-opus-4-6 --system-prompt "You are a reviewer"',
    continue: 'pi --mode json',
  },
];

API

spawnAgent(agent, prompt, options?)

Spawn a single pi agent. Returns AgentOutput.

spawnAgents(agents, prompt, options?)

Spawn multiple agents in parallel. Returns AgentOutput[].

parsePiOutput(raw)

Parse pi JSON event stream. Returns { sessionId, text }.

buildAgentCommand(agent, options)

Build the CLI command string for an agent. Exported for debugging/testing.

runCliWithStdin(command, content, timeout?)

Low-level: run a CLI command with stdin piped. Exported for advanced use.

Types

interface AgentDef {
  name: string;
  provider?: string;    // e.g. "anthropic"
  model?: string;       // e.g. "claude-opus-4-6"
  flags?: string;       // e.g. "--thinking high"
  start?: string;       // explicit start command
  continue?: string;    // explicit continue command
  sessionId?: string;   // existing session ID
}

interface SpawnOptions {
  piCommand?: string;   // default: "pi --mode json"
  piFlags?: string;     // default: ""
  timeout?: number;     // default: 600
}

interface AgentOutput {
  name: string;
  text: string;
  sessionId: string | undefined;
  error?: string;
}