Pi subagent

Delegate tasks to agents running in separate Pi processes. Each worker has its own context and saved session. The parent receives its final text and usage statistics, not its reasoning or tool transcript.

Requires Pi 0.87.1 or newer, using the @earendil-works SDK packages.

Install

pi install npm:oira666_pi-subagent
# Or install from Git:
pi install git:github.com/gee666/pi-subagent.git

To remove it:

pi remove npm:oira666_pi-subagent

Configuration

Use either pi-subagent.json or pi-subagents.json. Both filenames are permanently supported. User-configurable extension options have grouped JSON settings, with precedence environment > JSON > defaults.

{
  "limits": { "total": 50, "parallel": 30, "concurrency": 8 },
  "delegation": { "depth": 3, "preventCycles": true },
  "runner": { "startupTimeoutMs": 120000 }
}

See settings files for locations, all settings, environment mappings, and trust rules.

Extension controls

Exclude extensions from child agents without changing which extensions the parent loads:

PI_SUBAGENT_EXCLUDE_EXTENSIONS="oira666_pi-free-swarm,@scope/other-package,./local-extension.ts" pi

The originally requested hyphenated name is also supported. Use env because most shells cannot assign hyphenated variable names directly:

env 'PI-SUBAGENT-EXCLUDE-EXTENSIONS=oira666_pi-free-swarm' pi

Both variables accept comma-separated lists; whitespace and empty entries are ignored, and the two lists are combined. Entries match a package source, package name (including npm:@scope/name@version, ignoring the version), or an extension file/directory path. Automatic and settings-listed extension paths use the nearest owning package.json after resolving symlinks; loose hooks do not inherit the current workspace's or Pi configuration directory's package name. Relative paths resolve from the worker's working directory; ~/ and symlinks are supported. Commas inside paths are not supported in environment lists; use the JSON extension.exclude array for those paths. These variables are inherited by nested workers.

When a list is nonempty, the runner discovers enabled extensions without executing them, then launches the child with --no-extensions and explicit paths for every remaining extension, including authentication providers. This covers automatic user/project extensions and forwarded -e sources. An original --no-extensions still suppresses automatic extensions. Project resources are included only when the parent's live context trusts that working directory; unknown trust fails closed. The same trust decision is passed to the child. With no exclusions, launch behavior is unchanged and no extra discovery runs.

Discovery does not install packages or edit settings. Remote explicit -e sources must already be installed in Pi's user package location (or its supported legacy global npm location); temporary-only and project-only remote installs must first be installed there or passed as local paths. If Pi leaves a directory unresolved, pass its entry-point file explicitly so file exclusions cannot be bypassed by directory loading. Missing or invalid sources fail the launch rather than falling back to unfiltered loading. Pi's offline mode skips missing automatic packages, as usual. Filtering controls extension entry points, not code imported by an allowed extension, and the allowlist is a launch-time snapshot until the next delegation.

Disable this entire extension, including its tools, commands, flags, providers, and event handlers:

PI_SUBAGENT_DISABLED=1 pi

true (case-insensitive) also disables it; PI-SUBAGENT-DISABLED is an equivalent alias. Other values leave it enabled. The setting applies to the current process and is inherited by children. It is separate from child-extension exclusions, which do not disable anything in the parent. Restart Pi or reload extensions after changing the process environment.

Launch and resume

{
  "tasks": [
    { "task": "Implement the API", "max_subagents_allowed": 0 },
    { "task": "Review the design", "max_subagents_allowed": 0 }
  ]
}

Call subagents with one or more tasks. Tasks run in parallel, subject to the concurrency limit. Every task requires task text and a descendant allowance. The agent argument exists only when user-created agent definitions are available. The intelligence argument exists only when two or more enabled presets are configured. These choices are independent; with neither, task items contain only task and max_subagents_allowed. Use 0 for a worker that will not delegate, or 1 to let it launch one subagent. The caller reserves one slot for the worker plus its descendant allowance.

Workers with zero descendant allowance receive neither active delegation tools nor added delegation guidance. Raising max_subagents_allowed on resume restores the tools, subject to the depth limit. This uses Pi's documented getActiveTools() and setActiveTools() APIs during session_start. Workers that spent a positive allowance keep their tools so they can resume existing children.

Workers receive durable human names. Call resume_subagents to continue one with its previous context:

{ "resumes": [{ "subagent": "John", "task": "Now update the tests." }] }

agent selects a definition; subagent identifies an existing worker. Resumes do not consume new slots. See sessions and budgets for budget overrides, forks, and crash recovery.

Delegate only when parallel work or context isolation saves enough effort to cover worker startup and coordination. Pass existing findings with the task so workers do not repeat your research.

Agent definitions

There are no bundled agents. Without user-created definitions, every task uses the same default worker, with no agent-specific system prompt or instructions. It receives the parent's task text unchanged. Pi's normal system prompt and delegation limits still apply.

Create Markdown files in ~/.pi/agent/agents/, $PI_CODING_AGENT_DIR/agents/, or the project's .pi/agents/ directory:

---
name: writer
description: Writes technical documentation
thinking: low
first-layer: enabled
last-layer: disabled
tools: read,write
---

Write clear, concise technical documentation.

The body is appended to Pi's system prompt. Project definitions override user/environment definitions of the same name.

See configuration for frontmatter, layer restrictions, prompt overrides, and environment settings.

Interactive controls

Collapsed results show each child's name, task, status, and most recent activity anywhere in its subtree. Ctrl+O expands the newest call from memory without reading historical transcripts.

/subagent-expand <name> opens a saved worker transcript. With no name, it opens a searchable picker. Name completion is fuzzy. Each task or resume shows its actual provider/model and thinking level from the worker's session, not the parent's settings. Selected presets also appear as an intelligence label, kept separately for each run. Missing historical model/thinking metadata appears as unknown.

Model presets show labels such as Nicolas (Junior/code-writer) in regular tool results. One enabled preset applies automatically to new launches without exposing an intelligence argument. Two or more require an explicit intelligence choice on every launch item. Omitted or null choices reject the whole launch batch before any worker starts. Zero or disabled presets keep the existing launch defaults and show no intelligence label. Without an agent type, labels show Nicolas (Junior); without either qualifier, they show just Nicolas. Named resumes do not accept intelligence; they retain the original effective model, thinking, and label, even after configuration or parent settings change.

While workers run, steering input can be broadcast to selected names, including nested paths such as John > Maria. Only inputs marked as streaming steer open the routing prompt. Idle prompts and queued follow-ups remain with the parent.

The WITH SUBS footer includes recursive worker usage. Resuming or privately forking a named worker adds usage without increasing the unique-worker count. See usage accounting for programmatic results.

Development

npm ci
npm run check

Tests use the real SDK packages installed as development dependencies. No host loader or permissive type shims are needed. Run tests outside a delegated worker environment, or unset inherited PI_SUBAGENT_* storage and budget variables first.

Source organization:

Root entry points preserve existing imports. config.ts and agents.ts discover configuration and definitions. Runtime and test files stay below 350 lines; the name list is static data.

Attribution and license

Inspired by vaayne/agent-kit and pi-mono. MIT licensed.