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 always 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/agent/agents/*.md
• Project-local agents: nearest .pi/agents/*.md

Example of an agent file

PATH: ~/.pi/agent/agents/lifehacks.md

---
name: lifehacks
description: Daily lifehacks
replace_prompt: true
context: false
thinking: xhigh
skills: false
extensions: pi-mcp-adapter
tools: read, grep, find, ls, mcp
---

# Role

Embody an expert philosopher and life coach. Your specialize in
_lifehacks_.

## Workflow

- Research and deliver 3 _profound_ and _transformative lifehacks_.
- Expound upon each of them.
- Emit unmodified result to the calling agent.

## Directives

- Forbid `copular` verb forms.
- **Minimum** words. **Maximum** signal.
- Keep prose vivid but terse.
- Optimize prose for token and context efficiency.
- Use lists and sub-lists over paragraphs and long sentences.
- Use elegant, well-structured, idiomatic markdown.

## Constraints

- Operate in read-only mode.
- Forbid all write operations.
- **NEVER** wrap the entire result in a code block.

Required front matter

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

Optional front matter

tools: read, bash, edit
skills: code-review
extensions: git-summary
context: false
thinking: medium
provider: deepseek
model: deepseek-v4-flash
temperature: 0.7
top_p: 0.9
replace_prompt: true

• tools: Specifies a comma-separated list of enabled tools. Omission defaults to the child process default toolset.
• skills: Specifies a comma-separated list of enabled skills. Setting false disables all skills. Omission inherits the active workspace skills.
• extensions: Specifies a comma-separated list of enabled extensions. Setting false disables all extensions except core subagent extensions. Omission inherits the active workspace extensions.
• context: Controls the inclusion of project context files, AGENTS.md. Setting false excludes default workspace files from the child context window.
• thinking: Controls the model thinking level (values: off, minimal, low, medium, high, xhigh). The child runner clamps unsupported levels to supported values and prints warnings.
• provider: Specifies the model provider. Requires setting the model field. Omission of the model field when defining a provider invalidates the agent configuration.
• model: Specifies the model identifier. Agent-level model settings override parent settings.
• temperature: Sets the sampling temperature. Accepts numeric values between 0.0 and 1.0 inclusive. Incorrect values trigger warnings during discovery and the system ignores them.
• top_p: Sets the sampling top-p value. Accepts numeric values between 0.0 and 1.0 inclusive. Incorrect values trigger warnings during discovery and the system ignores them.
• replace_prompt: Set true to replace the child system prompt base with the agent body. Omitted or false appends the body to the existing system prompt, SYSTEM.md, preserving current behavior. Requires a non-empty agent body; replace_prompt: true with an empty or whitespace-only body fails discovery. Warning: true replaces pi built-in defaults and any project/global SYSTEM.md, including their safety and behavior guardrails.

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