@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: 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>".
• 🚀 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" }
  ]
}

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 templates.

The model priority chain is:

1. subagent.agents[role].model — per-role binding (settings)
2. .pi/agents/<name>.md frontmatter model
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-template frontmatter, subagent default, then the parent session. Built-in roles provide their documented thinking defaults.

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

License

MIT