@bytetrue/pi-subagent

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

Spawns focused child agents in isolated sessions for delegating tasks, background work, code reviews, or investigations, complete with real-time TUI progress streaming, token & cost tracking, and 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: Fast read-only codebase reconnaissance (read, grep, find, thinking: low).
  • researcher: Autonomous web & technical documentation research (read, grep, find, web_search, web_fetch, thinking: medium).
  • reviewer: Disciplined adversarial code review and test validation (read, grep, find, bash, thinking: high).
• 🛡️ 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>".
• 📊 Real-time TUI Card: Differential progress card showing live execution duration, current thinking intent, active tool call traces with arguments, token usage, and cost tracking (Alt+O to expand/collapse).
• ⚙️ /subagent Interactive Menu:
  • Task Monitor: View currently running, paused, and recent subagent tasks, inspect 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).
• 📟 Live Status Bar: Displays sub:N in the footer whenever any foreground or background subagent is actively executing.

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

Execute tasks in isolated child agent sessions. Multiple tasks run concurrently by default, or sequentially as a pipeline when chain: true. Supports non-blocking background execution with async: true.

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].model	string	No	Optional model override (e.g. gemini-3.7-flash, gpt-5:low).
tasks[i].thinking	string	No	Optional thinking level (off, low, medium, high, max).
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).
async	boolean	No	Set to true to run in the background and notify upon completion. Default: false.

Usage Examples

1. Single task:

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

2. Parallel fanout (multiple heterogeneous roles/models):

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

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" }
  ]
}

4. Background task (async: true):

{
  "async": true,
  "tasks": [{ "task": "Run end-to-end stress tests and summarize metrics" }]
}

Model Resolution

When no model is specified, subagents inherit the parent session's current model. The full priority chain:

1. tasks[i].model — per-task override
2. subagent.agents[role].model — per-role binding (settings)
3. .pi/agents/<name>.md frontmatter model
4. subagent.defaultModel — explicit subagent default (settings)
5. Parent session's current model (inherited)
6. The child pi process's own default

Note: root-level pi settings defaultProvider/defaultModel are deliberately not consulted — unset means "inherit", and the child process falls back to its own default by itself.

License

MIT