@bytetrue/pi-subagent

Lightweight, high-performance Subagent runner for Pi coding agent.

Spawns focused child agents in isolated sessions for delegating tasks, code reviews, or investigations. Every call returns at once; the parent agent keeps working (or ends its turn) and the full result arrives as a new message. Live progress, token & cost tracking sit in the status bar and the /subagent menu, with parallel/chain orchestration.

Features

• ⚡️ Zero Bloat & Minimal Context: Single lightweight tool schema (~150 tokens) replaces heavy multi-thousand-token multi-agent frameworks.
• 🎭 Built-in Golden Roles: scout, researcher, and reviewer ship as ordinary agent documents in agents/ — copy one into .pi/agents/ to customise it.
  • scout: Fast read-only codebase reconnaissance (read, grep, find, lowest thinking level).
  • researcher: Autonomous web & technical documentation research (read, grep, find, web_search, web_fetch, inherits the parent session's thinking level).
  • reviewer: Disciplined adversarial code review and test validation (read, grep, find, bash, highest thinking level).
• 🛡️ Runaway Guardrails: Default 20-minute timeout and 50-turn limit prevent infinite loops or burning quota.
• 🔄 Pi-native Session Resumption: Subagents assign clean project session IDs; paused or completed sessions can be resumed with resume: "<sessionId>".
• 🚀 Always Non-blocking: The tool call returns a task id immediately; the parent turn is never held. The complete output is delivered as a follow-up message that starts the next turn.
• 📊 Progress Where It Belongs: The footer shows sub:N · <role> <elapsed> for the oldest running task; /subagent → task → View Progress shows the detailed card (duration, thinking intent, tool traces with arguments, token usage, cost).
• ⚙️ /subagent Interactive Menu:
  • Task Monitor: View currently running, paused, and recent subagent tasks, inspect progress or output, or stop running tasks.
  • Fuzzy Model Search: Model picker with real-time text filter and wrap-around keyboard navigation (Up at top loops to bottom).
  • Back Navigation: Pressing Esc in any sub-menu smoothly returns to the parent menu level.
  • Role & Default Config: Configure global/project default models, thinking levels, and per-role overrides (built-in scout, researcher, reviewer or custom).

Installation

pi install npm:@bytetrue/pi-subagent

Or run directly from this repository:

pi -e packages/pi-subagent/src/index.ts

Interactive Configuration (/subagent)

Run /subagent in the Pi TUI to interactively:

• View Active Subagents: Browse all active/recent subagent tasks in the current session, view output, stop running tasks, or see resume instructions.
• Set default subagent model and thinking level: Use real-time fuzzy search to pick models across all configured providers with wrap-around cursor movement (Esc to go back).
• Configure specific roles: Customize scout, researcher, reviewer, or any custom role with dedicated model and thinking overrides.
• Run /subagent list or /subagent show: View effective configurations and discovered agent templates.

Tool Reference

subagent

Delegate tasks to isolated child agent sessions. Multiple tasks run concurrently by default, or sequentially as a pipeline when chain: true. The call always returns at once with a task id; the result arrives later as a new message.

Note: in print mode (pi -p, --mode json) the process exits after one turn, so a subagent started there has no next turn to report to. Pure background is the only mode by design (issue 088).

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | tasks | Array<TaskItem> | Yes | List of tasks to execute. | | tasks[i].task | string | Yes | The task instruction / prompt. | | tasks[i].agent | string | No | Optional agent role (loads prompt/defaults from .pi/agents/<name>.md). | | tasks[i].tools | string[] | No | Optional tool allowlist (e.g. ["read", "grep", "find"]). | | tasks[i].cwd | string | No | Optional working directory for the task. | | chain | boolean | No | Set to true to pipe output from step N to step N+1. Default: false (concurrent). | | timeoutMs | number | No | Global task timeout in ms. Default: 1200000 (20 minutes). | | maxTurns | number | No | Global turn limit before pausing. Default: 50. |

Usage Examples

1. Single task:

{
  "tasks": [{ "task": "Review packages/pi-subagent/src/index.ts for potential edge cases" }]
}

2. Parallel fanout (multiple roles):

{
  "tasks": [
    { "agent": "frontend-dev", "task": "Check UI components" },
    { "agent": "backend-dev", "task": "Verify API contracts" }
  ]
}

3. Sequential pipeline (chain: true):

{
  "chain": true,
  "tasks": [
    { "agent": "scout", "task": "Locate relevant test and config files" },
    { "agent": "reviewer", "task": "Perform adversarial review on the located files" }
  ]
}

Built-in roles

The built-in roles — scout, researcher, reviewer — are ordinary agent documents shipped in the package's agents/ directory. They are parsed by the same code as your own .pi/agents/*.md, and a file with the same name wins over the packaged one. Copy one out to customise it:

mkdir -p .pi/agents && cp node_modules/@bytetrue/pi-subagent/agents/scout.md .pi/agents/scout.md

---
model: your-provider/your-model
---

A document replaces the built-in entirely, so keep the fields you still want — tools in particular. Omitting tools leaves the child on pi's default set (read, bash, edit, write).

Model and Thinking Resolution

The Agent-facing tool deliberately does not expose model or thinking overrides. These execution-policy choices remain under user control through /subagent, settings, and agent documents.

The model priority chain is:

1. subagent.agents[role].model — per-role binding (settings)
2. An agent document — .pi/agents/<name>.md, <agentDir>/agents/<name>.md, or the packaged built-in
3. subagent.defaultModel — explicit subagent default (settings)
4. Parent session's current fully qualified provider/model (inherited)
5. The child pi process's own default

Thinking follows the same user-controlled chain: role settings, agent document, subagent default, then the parent session. scout asks for the lowest available thinking level and reviewer the highest; researcher sets none, so it inherits the parent session.

Root-level pi settings defaultProvider/defaultModel/defaultThinkingLevel are deliberately not consulted — unset subagent configuration means "inherit".

License

MIT