Subagents for pi

Designed to orchestrate agents for the SPAE framework. Agents in action.

---

Installation

Install from npm:

pi install npm:@mystilleef/pi-subagent

Try temporarily without installing:

pi -e npm:@mystilleef/pi-subagent

---

Features

• Asynchronous: Agents run in the background.
• Parallel: Run many agents simultaneously.
• Isolated: Each delegated task receives a separate context window.
• Nested: Subagents can spawn other subagents.
• Simple: No complex orchestration syntax.
• Bloat-free: No bundled agents. Write your own. Or use those from the SPAE Framework.

---

Usage

Run an agent with an optional task:

/run agent [optional task]

Examples:

/run spec implement google login screen
/run plan
/run inspect
/run build
/run verify

Use natural language to launch agents in parallel:

use the work agent to write a poem about linux; use the commit agent to make
commits; use the query agent to summarize the project.

Show active and completed jobs:

/jobs

Cancel running subagents:

/cancel-subagent

---

SPAE Workflow

The official extension for the SPAE Framework. The framework provides pre-built agents and skills for a structured, or orchestrated, workflow.

Structured

Phase	Agent	Purpose
1	/run spec <requirement>	Distill requirements into SPEC.md
2	/run plan	Decompose SPEC.md into an atomic task graph
3	/run inspect	Perform gap analysis and optimize PLAN.md
4	/run build	Carry out tasks from PLAN.md
5	/run verify	Verify implementation against SPEC.md

Orchestrated

Agent	Purpose
/run orchestrate <requirement>	Run all phases of the SPAE workflow
/run prepare <requirement>	Run preparatory phases of the SPAE workflow
/run spawn	Spawn build agents for each task in a plan

---

Agent definitions

This extension ships no agents. Define agents as Markdown files with YAML frontmatter and a Markdown system prompt body.

Discovery locations

• User-global agents: ~/.pi/agents/*.md
• Project-local agents: nearest .pi/agents/*.md

Required front matter

name: review
description: Review code for correctness and maintainability.

Optional front matter

tools: read, bash, edit
skills: code-review
thinking: medium
provider: deepseek
model: deepseek-v4-flash

Accepted thinking values

• off
• minimal
• low
• medium
• high
• xhigh

---

Tool

The extension also registers a subagent tool for model-driven delegation.

Inputs:

• agent: agent name.
• task: task prompt for the child agent.
• agentScope: optional lookup scope, one of user, project, or both.
• debug: optional flag that requests child diagnostic details. Full child messages and raw internals require PI_SUBAGENT_DEBUG_ENABLED=1 in the host environment.

---

Security

Subagents launch child pi --json processes. Agents, tools, and extensions run with user permissions, so treat agent definitions like executable automation.

Trust guidance:

• Review project-local agents before running them.
• Avoid delegating secrets unless the agent and tools need them.
• Treat child-agent prompts, tool arguments, stderr, and debug transcripts as potentially sensitive.
• Enable debug details only for trusted investigations. debug: true or /run --debug can expose child conversation transcripts, termination internals, and stderr only when the host explicitly sets PI_SUBAGENT_DEBUG_ENABLED=1.
• Prefer trusted repositories for shared agent definitions.
• Remember that child agents can call their configured tools.

---

Configuration and limits

Environment variables:

• PI_SUBAGENT_DEPTH: current nested subagent depth counter set internally for child processes.
• PI_SUBAGENT_MAX_DEPTH: max nested subagent depth. Default: 3. Values above 10 clamp to the internal ceiling 10; deeper nesting increases cost, latency, and runaway delegation risk.
• PI_SUBAGENT_AGENT_END_GRACE_MS: child process grace period after agent_end before forced termination. Default: 250.
• PI_SUBAGENT_MAX_STDERR_BYTES: max captured child stderr bytes. Default: 10000.
• PI_SUBAGENT_MAX_OUTPUT_BYTES: max returned output bytes. Default: 50000.
• PI_SUBAGENT_MAX_OUTPUT_LINES: max returned output lines. Default: 500.
• PI_SUBAGENT_DEBUG_ENABLED: debug detail authorization. Set to 1 to allow debug: true or /run --debug to include sanitized child messages, termination internals, and stderr; unset values keep non-debug detail behavior.

Limit variables parse as positive integers. Empty, zero, negative, decimal, Infinity, and non-numeric values fall back to defaults.

---

Troubleshooting

Missing agent:

• Confirm the file lives under ~/.pi/agents/ or the nearest .pi/agents/.
• Confirm frontmatter includes name and description.
• Confirm /run uses the name value, not the filename.

Project-local agent prompt:

• Pi may request confirmation before loading project-local agents when UI context exists.

Nested subagent blocked:

• Nested delegation hits the PI_SUBAGENT_MAX_DEPTH safety limit.
• Run the child task directly from the parent session instead.

Truncated output:

• Raise PI_SUBAGENT_MAX_OUTPUT_BYTES or PI_SUBAGENT_MAX_OUTPUT_LINES.
• Ask the child agent for a shorter summary.

---

Development

Install dependencies:

bun install

Run full verification:

bun verify

Check npm package contents:

bun pack:smoke