---
slug: "simple-subs"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/mcande21/simple-subs@main/README.md"
repo: "https://github.com/mcande21/simple-subs"
source_file: "README.md"
branch: "main"
---
# simple-subs

Lightweight subagent dispatch for [Pi](https://pi.dev). Spawn, coordinate, and collect results from parallel AI agents.

## Install

```bash
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:

```json
{
  "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](https://pi.dev) (pi-coding-agent)
- Node.js 22+

## License

MIT