pi-subagents is a Pi extension package that runs generic subagent tasks in separate child sessions and ships workflow prompt templates plus the wrapper code needed to execute those runs.

Install

Local path:

pi install /absolute/path/to/subagents

Git:

pi install https://gitea.rwiesner.com/pi/pi-subagents

Resources

Extension: ./index.ts
Prompts: ./prompts/*.md

Runner modes

default: background child process runner
optional tmux runner: set {"runner":"tmux"} in .pi/subagents.json or ~/.pi/agent/subagents.json

What a subagent run gets

delegated task text
selected model
optional working directory

Child runs are normal Pi sessions.

Presets

Subagent presets are discovered from markdown files. Locations:

global: ~/.pi/agent/subagents/*.md
nearest project: .pi/subagents/*.md (nearest ancestor directory)

Project presets override global presets by name. No built-in presets or roles are bundled with this package.

Preset frontmatter fields:

name (required)
description (required)
model (optional; provider/id)
tools (optional; comma-separated list or array)

Preset body becomes the child session system prompt. The tools field maps directly to Pi CLI --tools and limits which built-in tools are available to the child run.

Tools provided

subagent — foreground single or parallel runs using named presets
background_agent — detached process-backed run that returns immediately with a handle
background_agent_status — query background run counts and status

Requirements

default process runner: no tmux requirement
optional tmux runner: tmux must be available on PATH

Development

npm install
npm test