@xvzc/pi-subagents-minimal

A minimal pi extension for subagent invocation and inspection.

Packages

Package details

extension

Install @xvzc/pi-subagents-minimal from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@xvzc/pi-subagents-minimal
Package
@xvzc/pi-subagents-minimal
Version
1.1.0
Published
Sep 28, 2026
Downloads
616/mo · 514/wk
Author
xvzc
License
MIT
Types
extension
Size
287.1 KB
Dependencies
3 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-subagents-minimal

A minimal Pi extension for subagent invocation.

Installation

pi install npm:@xvzc/pi-subagents-minimal

To use it locally, clone the repository, install dependencies, and register the package as a Pi extension via its declared ./src/index.ts entry according to your Pi setup:

git clone <repo-url>
cd pi-subagents-minimal
npm install

Quick start

  1. Discover enabled roles: call subagent_list (takes no parameters).
  2. Start work: call subagent_call with type: "new", an agent name from the list, and a prompt. new and resume run in the background and return a queued acceptance promptly — do not poll with subagent_output.
  3. Collect the result: when a completion signal names a session, call subagent_output with that session_id. Reads are non-consuming and may be repeated.
  4. To continue the same session, call subagent_call with type: "resume", the session_id, and the follow-up prompt. To intervene in a running session immediately, use type: "steer" with the session_id.
  5. While subagents run, continue independent work. Completion notifications are pushed when children finish. For summaries only (never full output), call subagent_status.

Tools

Tool Purpose Key parameters
subagent_call Start (new), continue (resume), or immediately steer (steer) a subagent session. type, prompt; agent (required for new); session_id (required for resume/steer); optional model, thinking, workspaceDir (new only).
subagent_output Read the retained full report for one session. session_id.
subagent_list List enabled subagent roles. None.
subagent_status Show lifecycle summaries of active and recent sessions. None.

Session IDs are 16 lowercase hex digits grouped 8-4-4. Failures return a coded { error: { code, message } } envelope.

Configuration

Optional JSON file named pi-subagents-minimal.json, loaded from two paths with field-level precedence defaults < global < project:

  • Global: <agent-dir>/extensions/pi-subagents-minimal.json
  • Project: <cwd>/.pi/pi-subagents-minimal.json
Field Type Default Bounds / values
historyRetentionDays integer 7 1–3650
maxConcurrentSubagents integer 8 1–64
injectGuidelines boolean true true / false
defaultModel string absent non-empty string
defaultThinking string absent off, minimal, low, medium, high, xhigh, max

Missing files are silent; malformed files, invalid known fields, and unknown fields are ignored with a warning and never throw. The effective config is frozen at activation. Example:

{
  "historyRetentionDays": 7,
  "maxConcurrentSubagents": 8,
  "injectGuidelines": true
}

Development

Commands from package.json:

npm install
npm run check   # format:check + lint + typecheck + test
npm test        # vitest run
npm run build   # emits to dist/

Further detail

License

MIT — see LICENSE.