@piex-dev/subagent

Subagent delegation for pi — delegate focused tasks to isolated child agents via subprocess.

Status: MVP implemented. See docs/packages/subagent.md for the full design.

Install

pi install npm:@piex-dev/subagent

Local dev:

cd extensions/subagent && npm install && cd ../..
pi -e ./extensions/subagent/src/subagent.ts

What it does

The subagent tool spawns an isolated pi --mode json -p --no-session --no-extensions child process with its own system prompt, tools, and model config, then streams the result back. Two modes:

• single — { agent, task, context? }: one child agent.
• parallel — { tasks: [{ agent, task, context? }, ...] }: up to 8 concurrent children, each with its own agent role.

This is a blocking call: the main agent waits until the child finishes. Use it only when you need the result before continuing.

Built-in agents

| agent | role | tools | suggested model | | ---------- | ------------------ | ---------------------- | ------------------------ | | scout | read-only recon | read/grep/find/ls/bash | cheap+fast, thinking off | | planner | read-only planning | read/grep/find/ls | strong, thinking high | | reviewer | adversarial review | read/grep/find/ls/bash | strong, thinking high | | worker | implementation | default coding tools | inherit parent |

Configuration

Config lives under ~/.pi/piex-dev/subagent/:

• agents.yaml — user agent definitions (override built-ins by name)
• settings.json — defaultModel, defaultThinking, maxDepth, timeoutMs

agents.yaml example:

- name: reviewer
  description: Adversarial review
  systemPrompt: |
    You are a reviewer subagent. Report PASS/FAIL/PARTIAL. Do not edit files.
  tools: [read, grep, find, ls, bash]
  model: anthropic/claude-opus-4-1
  thinkingLevel: high

- name: scout
  description: Fast recon
  systemPrompt: Explore the codebase quickly and report grounded findings.
  tools: [read, grep, find, ls, bash]
  model: inherit
  thinkingLevel: off

Model resolution (three-tier)

1. agent model / thinkingLevel
2. settings.json defaultModel / defaultThinking
3. inherit the parent session's current model (read explicitly and passed to the child — not "omit --model")

Commands

• /subagents — list available agents and their effective model/thinking.

Design notes (MVP boundaries)

• Subprocess only (in-process transport is P1).
• Child runs with --no-extensions (no piex extension tools, no recursive subagent registration).
• Role prompts use --system-prompt (replace), not append.
• Optional context field passes diff/plan/summary; no automatic git-diff injection.
• Depth guard via PIEX_SUBAGENT_DEPTH (default maxDepth 1).
• Not in MVP: chain, fan-in, stateful mailbox, background async, watchdog. See roadmap in the design doc.

License

MIT