Pi Sub Agents Setup

README.md

Pi Subagents Guide

Delegate tasks to specialized sub-agents running in isolated pi processes. Each subagent gets its own context window, so the main conversation stays clean.

Installation

./install.sh

This symlinks the extension, agent definitions, and workflow prompts into ~/.pi/agent/.

Quick Start

Once installed, just ask pi to use agents naturally:

Use scout to find all authentication code

Pi will invoke the subagent tool, spawn a separate pi process with the scout's config, and stream results back.

---

Three Execution Modes

1. Single Agent

One agent, one task. Simplest mode.

Use scout to find how the database models are structured

Use worker to refactor the login function to use async/await

2. Parallel

Multiple agents run concurrently (up to 8 tasks, 4 concurrent). Use this when tasks are independent.

Run 2 scouts in parallel: one to find all API routes, one to find all database queries

Run 3 workers in parallel:
- Add input validation to the user endpoint
- Add input validation to the product endpoint  
- Add input validation to the order endpoint

All tasks stream updates simultaneously. You'll see live status for each: ⏳ running, ✓ done, ✗ failed.

3. Chain (Sequential Pipeline)

Steps run one after another. Each step receives the previous step's output via {previous}.

Use a chain: first have scout find the caching code, then have planner suggest improvements

If any step fails, the chain stops and reports which step failed.

---

Built-in Agents

Agent	Model	Tools	Purpose
scout	Haiku	read, grep, find, ls, bash	Fast codebase recon. Cheap and quick. Returns compressed findings for handoff.
planner	Sonnet	read, grep, find, ls	Creates implementation plans. Read-only — won't modify files.
reviewer	Sonnet	read, grep, find, ls, bash	Code review. Bash limited to git diff/log/show. Won't modify files.
worker	Sonnet	all default	General-purpose. Full read/write/bash capabilities.

Cost consideration: Scout uses Haiku (fast and cheap) for exploration. Planner, reviewer, and worker use Sonnet for deeper reasoning. Choose accordingly.

---

Workflow Prompts (Slash Commands)

Pre-built pipelines using chain mode:

/implement <task>

scout → planner → worker

Full implementation workflow. Scout gathers context, planner creates a plan, worker executes it.

/implement add Redis caching to the session store

/scout-and-plan <task>

scout → planner

Planning only — no changes are made. Good for reviewing an approach before committing.

/scout-and-plan refactor the auth module to support OAuth providers

/implement-and-review <task>

worker → reviewer → worker

Implement, get a code review, then apply the feedback. Self-improving loop.

/implement-and-review add comprehensive input validation to all API endpoints

---

Creating Custom Agents

Add a markdown file to ~/.pi/agent/agents/:

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

Your system prompt goes here. This is what the agent "knows" and how it behaves.

Be specific about constraints:
- What it should/shouldn't do
- Output format expectations
- Any domain knowledge

Frontmatter Fields

Field	Required	Description
name	Yes	Agent name (used to invoke it)
description	Yes	Shown when listing available agents
tools	No	Comma-separated tool list. Defaults to all tools.
model	No	LLM model. Defaults to current session model.

Tool Options

read, write, edit, bash, grep, find, ls

Restrict tools for safety — a reviewer shouldn't have write or edit.

Example: Security Auditor

---
name: security-auditor
description: Scans for common security vulnerabilities
tools: read, grep, find, ls
model: claude-sonnet-4-5
---

You are a security auditor. Scan the codebase for:
- SQL injection vulnerabilities
- XSS attack vectors
- Hardcoded secrets/credentials
- Insecure deserialization
- Missing input validation

Report findings with severity (critical/high/medium/low), file location, and remediation.

Usage:

Use security-auditor to scan the src/ directory

Example: Test Writer

---
name: test-writer
description: Writes unit tests for existing code
tools: read, write, bash, grep, find, ls
model: claude-sonnet-4-5
---

You write thorough unit tests. For each function:
1. Read the implementation
2. Identify edge cases
3. Write tests covering happy path, error cases, and boundaries
4. Run the tests to verify they pass

Use the project's existing test framework and conventions.

Usage:

Use test-writer to add tests for src/auth/login.ts

---

Project-Local Agents

For repo-specific agents, create .pi/agents/*.md in your project root. These require explicit opt-in:

Use worker with agentScope "both" to implement the feature

Or set agentScope: "project" to use only project agents. Pi will prompt for confirmation before running project-local agents (security measure since they're repo-controlled).

---

Custom Workflow Prompts

Add markdown files to ~/.pi/agent/prompts/:

---
description: Short description shown in /help
---
Use the subagent tool with the chain parameter to execute this workflow:

1. First, use the "scout" agent to find: $@
2. Then, use the "worker" agent to fix issues found (use {previous} placeholder)

Execute this as a chain, passing output between steps via {previous}.

$@ is replaced with whatever the user types after the slash command.

Save as ~/.pi/agent/prompts/find-and-fix.md, then use:

/find-and-fix all deprecated API calls

---

Tips

• Use scout for exploration — it's cheap (Haiku) and gives you codebase context without cluttering the main conversation.
• Parallel for independent tasks — don't chain what can run concurrently.
• Chain for dependent tasks — when step 2 needs step 1's output.
• Ctrl+O to expand — collapsed view shows last 5-10 items; expand to see full output with markdown rendering.
• Ctrl+C propagates — aborting kills the subagent subprocess cleanly.
• Agents are re-discovered on each call — edit agent .md files mid-session and changes take effect immediately.

install.sh

#!/usr/bin/env bash
#
# install.sh
#
# Installs the pi subagent extension, which lets you delegate tasks to
# specialized sub-agents running in isolated pi processes.
#
# What gets installed:
#   ~/.pi/agent/extensions/subagent/  — the extension (index.ts + agents.ts)
#   ~/.pi/agent/agents/               — agent definitions (scout, planner, reviewer, worker)
#   ~/.pi/agent/prompts/              — workflow prompt templates (/implement, /scout-and-plan, etc.)
#
# Usage:
#   chmod +x install-pi-subagents.sh
#   ./install-pi-subagents.sh
#

set -euo pipefail

# ─── Locate the pi package ───────────────────────────────────────────────────
# Find where @mariozechner/pi-coding-agent is installed globally.
PI_PKG="$(npm root -g)/@mariozechner/pi-coding-agent"
SUBAGENT_DIR="$PI_PKG/examples/extensions/subagent"

if [ ! -d "$SUBAGENT_DIR" ]; then
    echo "ERROR: Could not find pi subagent extension at:"
    echo "  $SUBAGENT_DIR"
    echo ""
    echo "Make sure @mariozechner/pi-coding-agent is installed globally:"
    echo "  npm install -g @mariozechner/pi-coding-agent"
    exit 1
fi

echo "Found pi package at: $PI_PKG"

# ─── 1. Install the extension ────────────────────────────────────────────────
# The extension consists of two files:
#   - index.ts: registers the "subagent" tool with pi (supports single, parallel, chain modes)
#   - agents.ts: agent discovery logic (finds .md agent definitions)
# We symlink them so updates to the pi package automatically apply.

echo ""
echo "Installing subagent extension..."
mkdir -p ~/.pi/agent/extensions/subagent

ln -sf "$SUBAGENT_DIR/index.ts" ~/.pi/agent/extensions/subagent/index.ts
ln -sf "$SUBAGENT_DIR/agents.ts" ~/.pi/agent/extensions/subagent/agents.ts

echo "  ✓ ~/.pi/agent/extensions/subagent/index.ts"
echo "  ✓ ~/.pi/agent/extensions/subagent/agents.ts"

# ─── 2. Install agent definitions ────────────────────────────────────────────
# Agents are markdown files with YAML frontmatter specifying:
#   - name, description: identity
#   - tools: which tools the agent can use (e.g., read, grep, bash)
#   - model: which LLM model to use (e.g., claude-haiku-4-5 for speed)
#
# Built-in agents:
#   scout.md    — fast codebase recon using Haiku (cheap/fast)
#   planner.md  — creates implementation plans using Sonnet (read-only)
#   reviewer.md — code review specialist using Sonnet (read-only + git)
#   worker.md   — general-purpose with full tool access using Sonnet

echo ""
echo "Installing agent definitions..."
mkdir -p ~/.pi/agent/agents

for f in "$SUBAGENT_DIR"/agents/*.md; do
    name="$(basename "$f")"
    ln -sf "$f" ~/.pi/agent/agents/"$name"
    echo "  ✓ ~/.pi/agent/agents/$name"
done

# ─── 3. Install workflow prompt templates ─────────────────────────────────────
# Prompt templates are slash commands you can invoke in pi:
#   /implement <task>            — scout → planner → worker (full workflow)
#   /scout-and-plan <task>       — scout → planner (planning only, no changes)
#   /implement-and-review <task> — worker → reviewer → worker (implement + review cycle)
#
# These use the "chain" mode where each step's output feeds into the next
# via the {previous} placeholder.

echo ""
echo "Installing workflow prompts..."
mkdir -p ~/.pi/agent/prompts

for f in "$SUBAGENT_DIR"/prompts/*.md; do
    name="$(basename "$f")"
    ln -sf "$f" ~/.pi/agent/prompts/"$name"
    echo "  ✓ ~/.pi/agent/prompts/$name"
done

# ─── Done ─────────────────────────────────────────────────────────────────────
echo ""
echo "Installation complete! You can now use subagents in pi:"
echo ""
echo "  Single:    'Use scout to find all auth code'"
echo "  Parallel:  'Run 2 scouts in parallel: one for models, one for providers'"
echo "  Chain:     '/implement add Redis caching to the session store'"
echo ""
echo "To create custom agents, add .md files to ~/.pi/agent/agents/"
echo "See: $SUBAGENT_DIR/README.md"