co-mono/packages/coding-agent/examples/custom-tools/subagent/README.md

Subagent Example

Delegate tasks to specialized subagents with isolated context windows.

Structure

subagent/
├── README.md            # This file
├── subagent.ts          # The custom tool
├── agents/              # Sample agent definitions
│   ├── scout.md         # Fast recon, returns compressed context
│   ├── planner.md       # Creates implementation plans
│   ├── reviewer.md      # Code review
│   └── worker.md        # General-purpose (full capabilities)
└── commands/            # Workflow presets
    ├── implement.md     # scout -> planner -> worker
    ├── scout-and-plan.md    # scout -> planner (no implementation)
    └── implement-and-review.md  # worker -> reviewer -> worker

Installation

From the examples/custom-tools/subagent/ directory:

# Copy the tool
mkdir -p ~/.pi/agent/tools
cp subagent.ts ~/.pi/agent/tools/

# Copy agents
mkdir -p ~/.pi/agent/agents
cp agents/*.md ~/.pi/agent/agents/

# Copy workflow commands
mkdir -p ~/.pi/agent/commands
cp commands/*.md ~/.pi/agent/commands/

Security Model

This example intentionally executes a separate pi subprocess with a delegated system prompt and tool/model configuration.

Treat project-local agent definitions as repo-controlled prompts:

• A project can define agents in .pi/agents/*.md.
• Those prompts can instruct the model to read files, run bash commands, etc. (depending on the allowed tools).

Default behavior: the tool only loads user-level agents from ~/.pi/agent/agents.

To enable project-local agents, pass agentScope: "both" (or "project") explicitly. Only do this for repositories you trust.

When running interactively, the tool will prompt for confirmation before running project-local agents. Set confirmProjectAgents: false to disable the prompt.

Usage

Single agent

> Use the subagent tool with agent "scout" and task "find all authentication code"

Parallel execution

> Use subagent with tasks:
>   - scout: "analyze the auth module"
>   - scout: "analyze the api module"
>   - scout: "analyze the database module"

Chained workflow

> Use subagent chain:
>   1. scout: "find code related to caching"
>   2. planner: "plan Redis integration using: {previous}"
>   3. worker: "implement: {previous}"

Workflow commands

/implement add Redis caching to the session store
/scout-and-plan refactor auth to support OAuth
/implement-and-review add input validation to API endpoints

Tool Modes

Mode	Parameter	Description
Single	{ agent, task }	One agent, one task
Parallel	{ tasks: [...] }	Multiple agents run concurrently
Chain	{ chain: [...] }	Sequential with {previous} placeholder

Flow Diagrams

Single Mode

┌─────────────────┐
│   Main Agent    │
└────────┬────────┘
         │ "use scout to find auth code"
         ▼
┌─────────────────┐
│  subagent tool  │
└────────┬────────┘
         │ pi -p --model haiku ...
         ▼
┌─────────────────┐
│     Scout       │
│   (subprocess)  │
└────────┬────────┘
         │ stdout
         ▼
┌─────────────────┐
│   Tool Result   │
└─────────────────┘

Parallel Mode

┌──────────────────────┐
│      Main Agent      │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│    subagent tool     │
│    Promise.all()     │
└──────────┬───────────┘
           │
     ┌─────┼─────┐
     ▼     ▼     ▼
┌──────┐┌──────┐┌──────┐
│Scout ││Scout ││Scout │
│ auth ││ api  ││  db  │
└──┬───┘└──┬───┘└──┬───┘
   │       │       │
   └───────┼───────┘
           ▼
┌──────────────────────┐
│   Combined Result    │
└──────────────────────┘

Chain Mode

┌─────────────────┐
│   Main Agent    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  subagent tool  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Step 1: Scout  │
└────────┬────────┘
         │ {previous} = scout output
         ▼
┌─────────────────┐
│ Step 2: Planner │
└────────┬────────┘
         │ {previous} = planner output
         ▼
┌─────────────────┐
│ Step 3: Worker  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Chain Result   │
└─────────────────┘

Workflow Command Expansion

/implement add Redis
        │
        ▼
┌─────────────────────────────────────────┐
│  Expands to chain:                      │
│  1. scout: "find code for add Redis"    │
│  2. planner: "plan using {previous}"    │
│  3. worker: "implement {previous}"      │
└─────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────┐
│            Chain Execution              │
│                                         │
│ scout ──► planner ──► worker            │
│ (haiku)   (sonnet)    (sonnet)          │
└─────────────────────────────────────────┘

Agent Definitions

Agents are markdown files with YAML frontmatter:

---
name: my-agent
description: What this agent does
tools: read, grep, find, ls
model: claude-haiku-4-5
---

System prompt for the agent goes here.

Locations:

• ~/.pi/agent/agents/*.md - User-level (global)
• .pi/agents/*.md - Project-level (only loaded if agentScope includes "project")

Sample Agents

Agent	Purpose	Model
scout	Fast codebase recon, returns compressed context	Haiku
planner	Creates implementation plans from context	Sonnet
reviewer	Code review for quality/security	Sonnet
worker	General-purpose with full capabilities	Sonnet

Workflow Commands

Commands are prompt templates that invoke the subagent tool:

Command	Flow
/implement <query>	scout -> planner -> worker
/scout-and-plan <query>	scout -> planner
/implement-and-review <query>	worker -> reviewer -> worker

Limitations

• No timeout/cancellation (subprocess limitation)
• Output truncated to 500 lines / 50KB per agent
• Agents discovered fresh on each invocation