simple-subs

Lightweight subagent dispatch for Pi. Spawn, coordinate, and collect results from parallel AI agents.

Install

pi install npm:simple-subs

Features

• Single dispatch — spawn one agent, capture output
• Parallel dispatch — fan-out N agents with concurrency control
• Async dispatch — background agents with status polling
• Peer messaging — filesystem-based inbox protocol between parallel agents
• Context resume — structured reasoning handoff between sequential dispatches
• Fork context — branch parent session for child agent continuity
• Intercom bridge — supervisor escalation via pi-intercom
• Model routing — automatic model selection from dispatch depth
• Compact TUI — animated spinners, status glyphs, live parallel progress

Usage

Single dispatch

subagent({
  agent: "edi",
  task: "Implement the retry logic",
  output: "/tmp/edi-report.md",
  outputMode: "file-only"
})

Parallel dispatch

subagent({
  tasks: [
    { agent: "garrus", task: "Research auth module", output: "/tmp/garrus.md", outputMode: "file-only" },
    { agent: "liara", task: "Research API layer", output: "/tmp/liara.md", outputMode: "file-only" }
  ],
  concurrency: 2
})

Parallel agents automatically get peer inbox directories for coordination. Messages are delivered between tool calls via filesystem writes.

Async dispatch

subagent({
  agent: "edi",
  task: "Long-running analysis",
  async: true
})

// Check status
subagent({ action: "status", id: "run-id" })

Model routing

subagent({
  agent: "edi",
  task: "...",
  depth: 3  // auto-selects model tier: 1-2=sonnet, 3=sonnet, 4-5=opus
})

Context resume

Agents can write resume files for downstream consumers:

subagent({
  agent: "edi",
  task: "...",
  resume: "/tmp/scout-resume.md"  // upstream reasoning injected into task
})

List agents

subagent({ action: "list" })

Peer Messaging Protocol

Parallel agents exchange typed messages through filesystem inboxes:

{
  "from": "garrus",
  "type": "finding",
  "topic": "auth",
  "confidence": "high",
  "body": "Token refresh skips validation"
}

Message types: finding, dead-end, question, answer, update

Messages are delivered automatically between tool calls. A parent inbox captures all peer traffic for orchestrator monitoring.

TUI

Compact display while agents work:

⠹ edi(Implement retry logic) · 12.3s

Parallel progress with per-agent completion:

⠼ 3 agents [✓edi, ✓garrus, tali] · 2/3 · 18.4s

Completion summary:

✓ edi · 12.3s · 5 tools · 450 tokens · $0.0034 → 48 lines

Requirements

• Pi (pi-coding-agent)
• Node.js 22+

License

MIT