pi-subagent-lite

Lightweight subagent for pi — async, concurrent, file-based results.

A minimal pi extension that delegates tasks to isolated pi child processes. Each subagent writes its result to a file you specify. It supports single-task delegation and one-call parallel tasks[] batches. No chains, no management CRUD, no attention tracking — just spawn, work, write.

Install

pi install npm:pi-subagent-lite

Git and local development alternatives:

pi install git:github.com/smithyyang/pi-subagent-lite
pi -e ./src/index.ts

Usage

After installing, tell pi to use subagents:

List available agents and inspect their details, then delegate a research task.

The model will:

1. Call subagent(action="list") to discover available agents
2. Call subagent(action="get", agent="explorer") to inspect an agent's details
3. Call subagent(tasks=[{agent:"explorer", prompt:"...", output:"/tmp/result.md"}]) to delegate; use one array item for one subagent, or multiple items for parallel subagents

Parameters

Parameter	Type	Required	Default	Description
action	string	No	—	"list" to discover agents, "get" to inspect an agent. Omit to delegate.
agent	string	For get only	—	Agent name to inspect. For delegation, put agent inside each tasks[] item.
tasks	array	For delegation	—	Array of { agent, prompt, output }. One item = one subagent; multiple items = parallel subagents in one batch.
async	boolean	No	true	Run in background. false waits for all tasks to complete.

Usage Notes (shown to the model)

The tool's description instructs the model to:

1. Use action="list" first to discover agents before delegating.
2. Use action="get" to review an agent's full description, tools, and config.
3. Always delegate via tasks[]. Launch multiple subagents concurrently by putting multiple items in one tasks[] array.
4. Once delegated, do not duplicate the work — continue with non-overlapping tasks.
5. Async batches notify the main agent once when the whole batch finishes; read output files and summarize results for the user.
6. Each subagent starts fresh — provide a highly detailed, self-contained task.
7. Tell the subagent whether to write code or do research; it does not inherit your session context.

Agent Definitions

Agents are markdown files with YAML frontmatter in ~/.pi/agent/agents/ (global) or .pi/agents/ (project).

Example: ~/.pi/agent/agents/reviewer.md

---
name: reviewer
description: Code review specialist. Reviews code changes for bugs, security issues, and style violations
tools: read, grep, bash
model: anthropic/claude-sonnet-4-20250514
---

You are an expert code reviewer. Review the provided code or changes for:
1. Bugs and logic errors
2. Security vulnerabilities
3. Performance issues
4. Style and maintainability

Provide specific, actionable feedback with file paths and line numbers.

Frontmatter Fields

Field	Required	Default	Description
name	Yes	filename	Agent identifier used in tool calls
description	Yes	—	What the agent does (shown to main agent via action="list")
model	No	pi default	Model override (e.g. anthropic/claude-sonnet-4-20250514)
thinking	No	pi default	Thinking level: off, low, medium, high
tools	No	all built-in	Comma-separated allowlist: read, bash, edit, write, grep, find, ls
extensions	No	none	Extension paths to load in the child

The body of the markdown file becomes the agent's system prompt (appended to pi's default prompt via --append-system-prompt).

Agent Locations (priority order)

1. Project: .pi/agents/*.md (highest priority)
2. User: ~/.pi/agent/agents/*.md
3. Built-in: bundled with this package

Commands

Command	Description
/subagents	List all running and completed async subagent runs

Architecture

flowchart LR
    Parent[Pi parent agent] -->|subagent tool call| Extension[pi-subagent-lite]
    Extension --> Discovery[Agent discovery]
    Extension --> Coordinator[Sync / async batch coordinator]
    Coordinator --> ChildA[Isolated pi child process]
    Coordinator --> ChildB[Isolated pi child process]
    ChildA --> OutputA[Caller-selected output file]
    ChildB --> OutputB[Caller-selected output file]
    ChildA --> Logs[Redacted diagnostics under /tmp]
    ChildB --> Logs
    Coordinator -->|one event per completed batch| Parent

The parent and children do not share conversation context. Each child receives an explicit agent prompt, tool/model configuration, and an authoritative output-file contract. Async batches return immediately and emit one completion event only after every child has settled.

How It Works

1. Model calls subagent(action="list") to see available agents
2. Model calls subagent(action="get", agent="name") to inspect agent details
3. Model calls subagent(tasks=[{agent, prompt, output}], async=true); one task item starts one subagent, multiple items start a parallel batch
4. Extension spawns separate pi processes with each agent's system prompt and tools
5. Each subagent runs fully isolated — its own model, tools, and session
6. Each task includes an instruction to write the result to its output file
7. When async=true, control returns immediately; the parent continues working
8. When async=false, the parent waits for all child processes to finish
9. Async batches send one follow-up notification when all subagents finish
10. Child runs keep local diagnostics under /tmp/pi-subagent-lite-runs/<batchId>/<runId>/ for manual inspection; diagnostics are not part of the model-facing workflow.

Async Workflow

Model: subagent(action="list")
  → Gets: ["explorer", "web-search", ...]

Model: subagent(action="get", agent="explorer")
  → Gets: full agent detail (description, tools, system prompt, model)

Model: subagent(tasks=[
  {agent:"explorer", prompt:"Find API routes", output:"/tmp/api-routes.md"},
  {agent:"researcher", prompt:"Research framework docs", output:"/tmp/docs.md"}
], async=true)
  → Returns: batch_id: "abc123" and run ids

Model: (continues working on non-overlapping task...)
  → Gets a follow-up notification when the whole batch finishes

Local Diagnostics

Each child subagent run writes a local diagnostics directory under /tmp/pi-subagent-lite-runs/<batchId>/<runId>/. This is for humans/plugin developers only and is not shown to the main agent in tool descriptions, notifications, or TUI rows:

File	Description
task.md	Exact task passed to the child
output-contract.md	System-level file output contract
args.json	Child pi command arguments, model, tools, extensions
events.jsonl	JSON event stream from the child process, with hidden reasoning fields redacted
tool-calls.jsonl	Tool execution start/end events
messages.md	Visible user/tool/assistant messages captured from the run
stdout.jsonl	Redacted JSON stdout events
stderr.txt	Child stderr
status.json	Run status, output path, exit code, error

Logs live in /tmp, so they are temporary and won't grow your .pi directory.

Design Philosophy

• One tool with discovery — subagent does everything: list, inspect, delegate.
• Discover before delegate — The model must first list then inspect agents before using them.
• File-based results — The output file is the contract. No stdout fallback masks failures.
• Async by default — Fire and forget. A batch-level callback notifies the main agent when done.
• No concurrency limits — Spawn as many as you want. The OS handles scheduling.
• Parallel without chains — Use tasks[] for one-call fan-out; no chain DSL or orchestration framework.
• No management API — Agents are files. Add/remove by creating/deleting .md files.

License

MIT — see LICENSE.