Dispatch Lite

A minimal multi-agent dispatcher for Pi Coding Agent. The primary Pi agent has no codebase tools — it can only delegate work to specialist sub-agents via a single dispatch_agent tool. Each sub-agent runs as a separate pi process with its own tool set.

Prerequisites

Tool	Version	Install
Pi Coding Agent	>= 0.55	npm i -g @mariozechner/pi-coding-agent
Bun	>= 1.0	curl -fsSL https://bun.sh/install | bash
just	any	brew install just (macOS) or cargo install just

You also need a working LLM provider configured for Pi (e.g. OpenRouter API key in your .env).

Setup

# Copy or clone the dispatch-lite folder into any project
cp -r dispatch-lite /path/to/your-project/
cd /path/to/your-project/dispatch-lite

# Install dev dependencies (only needed for running tests)
bun install

No runtime node_modules are needed — Pi's built-in jiti runtime resolves all imports at load time.

Quick Start

# From inside the dispatch-lite folder:
just start

# Or from anywhere, point Pi at the extension:
pi -e /path/to/dispatch-lite/dispatch-lite.ts

On startup you'll see:

Dispatch Lite: 3 agents loaded (scout, builder, reviewer)

The dispatcher agent has no file tools — it can only think and delegate. Ask it something and it will route to the right sub-agent.

Agents

Three agents are included in agents/:

Agent	Tools	Purpose
scout	read, grep, find, ls	Read-only recon — explores the codebase and reports findings
builder	read, write, edit, bash, grep, find, ls	Read-write — implements changes, writes code
reviewer	read, bash, grep, find, ls	Read-only — reviews code for bugs, security, style

Adding Your Own Agent

Create a .md file in dispatch-lite/agents/ with YAML frontmatter:

---
name: my-agent
description: What this agent does (one line)
tools: read,grep,find,ls
---
You are a specialist agent. Your instructions go here.

Fields:

• name (required) — used to dispatch, case-insensitive
• description — shown in the dispatcher's system prompt
• tools — comma-separated Pi tool names (defaults to read,grep,find,ls)
• Everything after --- is the agent's system prompt

Restart Pi and the new agent is automatically available.

Usage Examples

Example 1: Explore project structure

You: What's the structure of this project? Give me a high-level overview.

The dispatcher will route this to scout, which reads the directory tree and key files, then reports back.

Example 2: Find and fix TODOs

You: Find all TODO comments in the codebase and fix the most critical ones.

The dispatcher will:

1. Dispatch scout to grep for TODOs across the codebase
2. Review the results and pick the critical ones
3. Dispatch builder to implement the fixes

Example 3: Code review a file

You: Review dispatch-lite/src/dispatch.ts for bugs and improvements.

The dispatcher sends this to reviewer, which reads the file, checks for issues, and returns a bullet-point report.

Example 4: Multi-step feature implementation

You: Add a "tester" agent that runs bun test and reports results.

The dispatcher will:

1. Dispatch scout to understand the existing agent structure
2. Dispatch builder to create agents/tester.md with the right frontmatter
3. Optionally dispatch reviewer to sanity-check the new agent definition

Example 5: Chained investigation

You: Is there any dead code in the src/ directory? Remove it if you find any.

The dispatcher chains scout (find unused exports/functions) then builder (delete the dead code), then optionally reviewer (verify nothing broke).

Running Tests

# From inside dispatch-lite/
just test

# Or directly:
bun test

Tests cover the pure functions (frontmatter parsing, agent scanning, prompt building) — no Pi runtime needed.

Project Structure

dispatch-lite/
  agents/
    scout.md              # Read-only recon agent
    builder.md            # Read-write implementation agent
    reviewer.md           # Read-only code review agent
  src/
    types.ts              # Shared interfaces (AgentDef, AgentState, DispatchResult)
    parse.ts              # Pure: frontmatter parser, agent dir scanner, catalog builder
    prompt.ts             # Pure: dispatcher system prompt builder
    dispatch.ts           # Side-effectful: spawn("pi") sub-agent runner
  dispatch-lite.ts        # Pi extension entry point
  parse.test.ts           # Unit tests for parse.ts
  prompt.test.ts          # Unit tests for prompt.ts
  package.json            # Dev dependencies and scripts
  justfile                # Task runner recipes
  README.md               # This file

How It Works

1. Session start — the extension scans dispatch-lite/agents/ for .md files, parses frontmatter, and builds an agent catalog
2. System prompt override — the dispatcher's system prompt is injected with the full agent catalog (names, descriptions, tools) so it knows who to call
3. Tool lockdown — pi.setActiveTools(["dispatch_agent"]) removes all codebase tools from the primary agent, forcing it to delegate
4. Dispatch — when the dispatcher calls dispatch_agent({ agent: "scout", task: "..." }), a child pi process is spawned with that agent's tools and system prompt
5. Result — the sub-agent's text output streams back and is returned to the dispatcher, which synthesizes a response for the user