@fosterg4/pi-subagent

Delegate complex tasks to specialized sub-agents with isolated context windows, structured JSON handoff, contract schemas, and live TUI streaming — all within pi.

Features

• Isolated context — Each subagent runs in a separate pi process with its own context window
• Three execution modes — Single, parallel (max 8, concurrency 4), and chain (sequential with data handoff)
• Structured JSON handoff — Agents pass typed data between each other, not freeform markdown
• Contract schemas — inputSchema/outputSchema in agent frontmatter ensures valid handoffs
• Live TUI streaming — Subagent tool calls (read, bash, grep, etc.) stream in real-time
• Bundled agents — 4 built-in agents ready to use: scout, planner, reviewer, worker
• Workflow prompts — /implement, /scout-and-plan, /implement-and-review commands

Installation

pi install npm:@fosterg4/pi-subagent

For a quick test without installing:

pi -e npm:@fosterg4/pi-subagent

Usage

Single agent

Ask the LLM to use a subagent:

Use scout to find all authentication code in the project

The LLM will call the subagent tool with { agent: "scout", task: "..." }.

Parallel execution

Run 2 scouts in parallel: one to find models, one to find providers

Chained workflow

Use a chain: first have scout find the read tool, then have planner suggest improvements

Workflow prompts

/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

Bundled Agents

| Agent | Purpose | Default Model | |-------|---------|---------------| | scout | Fast codebase recon — returns structured findings | claude-haiku-4-5 | | planner | Creates implementation plans from context & requirements | claude-sonnet-4-5 | | reviewer | Code review — quality, security, maintainability | claude-sonnet-4-5 | | worker | General-purpose implementation with full capabilities | claude-sonnet-4-5 |

Each agent has a defined inputSchema and outputSchema in its frontmatter, ensuring structured data flows between chained agents.

Tool Parameters

The subagent tool accepts three mutually exclusive modes:

Single mode

{
  "agent": "scout",
  "task": "Find all authentication code",
  "cwd": "/optional/working/directory"
}

Parallel mode

{
  "tasks": [
    { "agent": "scout", "task": "Find models" },
    { "agent": "scout", "task": "Find providers" }
  ]
}

Chain mode

{
  "chain": [
    { "agent": "scout", "task": "Investigate the codebase" },
    { "agent": "planner", "task": "Create a plan from: {previous}" }
  ]
}

Common options

| Option | Type | Default | Description | |--------|------|---------|-------------| | agentScope | "user", "project", "both" | "user" | Which agent directories to search | | confirmProjectAgents | boolean | true | Prompt before running project agents | | cwd | string | current dir | Working directory for subprocess |

Custom Agents

Create your own agents as .md files with YAML frontmatter:

---
name: my-agent
description: What this agent does
tools: read, grep, find, ls, bash
model: claude-haiku-4-5
inputSchema:
  type: object
  properties:
    query:
      type: string
  required: [query]
outputSchema:
  type: object
  properties:
    result:
      type: string
  required: [result]
---

System prompt for the agent goes here.

Agent locations (priority: project > user > bundled):

• ~/.pi/agent/agents/*.md — User-level (always loaded)
• .pi/agents/*.md — Project-level (requires agentScope: "project" or "both")
• Bundled with package — Lowest priority, always available

Security

• User agents (~/.pi/agent/agents/): Always trusted
• Project agents (.pi/agents/): Requires confirmation prompt before execution
• Bundled agents: Trusted by virtue of package installation

Development

# Clone and test locally
git clone https://github.com/fosterg4/pi-subagent.git
cd pi-subagent

# Test with pi
pi -e ./index.ts

# Publish
npm publish --access public

License

MIT