nicobailon/pi-subagents

Pi extension for async subagent delegation with truncation, artifacts, and session sharing

What is pi‑subagents?

pi‑subagents is an extension for the Pi AI‑assistant platform that lets a single Pi session spawn focused child agents (called subagents) to handle specific pieces of work. Think of it as giving your AI “assistant” a team of specialists that can run in the foreground or in the background, report back, and be orchestrated with natural language commands.

Core idea

Parent session (Pi) stays in control of the conversation.
When you ask for a subagent (e.g., “Use reviewer to review this diff”), Pi launches a child Pi session with a dedicated role.
The child does its job (code review, research, implementation, etc.) and returns the result to the parent.
Children can run inline (foreground) – streaming their output directly in the chat – or detached (background) – continuing after you return to the main conversation.

Built‑in agents (ready‑to‑use)

Agent	Typical use
scout	Quickly map a codebase: list relevant files, entry points, data flow, and risks.
researcher	Pull information from the web or docs, cite sources, and produce a concise brief.
evidence‑auditor	Verify that research claims are actually backed by the cited sources.
worker	Perform implementation: edit files, run validation, and ask for approval before making guesses.
reviewer	Code review – check correctness, test coverage, edge‑cases, and simplicity; optionally apply small fixes.
oracle	Give a second opinion on a plan, challenge assumptions, and point out blind spots (no file edits).
delegate	A lightweight general‑purpose helper that behaves similarly to the parent session.

How you interact with it

You don’t need to write config files or learn special slash commands. After installing the package with:

pi install npm:pi-subagents

just ask Pi in plain language, for example:

Use reviewer to review this diff.
Ask oracle for a second opinion on my current plan.
Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity. Pi decides which subagent to launch, whether it should run in the foreground or background, and how to compose the results.

Typical workflows

Goal	Natural language prompt
Get a second opinion	`Ask oracle to review this plan and challenge assumptions.`
Solve a hard bug	`Use oracle to investigate this bug before we edit.`
Review a pull‑request diff	`Use reviewer to review this diff.`
Run several reviewers at once	`Run reviewers for correctness, tests, and cleanup.`
Conduct a debate among multiple advisors	`Use /council with model‑based advisors to compare this decision.`
Implement then verify	`Implement this, then review it.`
Continuous review loop	`Run a review loop on this change with a max of 3 rounds.`
Background execution	`Run this in the background.`
Inspect running work	`Show me the current async runs.`

The extension also ships with shortcut commands like /parallel‑review and /review‑loop that encode these patterns for repeatable use.

Observability & control

Foreground runs stream live in the chat.
Background runs appear in a persistent FleetView panel below the editor. You can open a live inspector with /subagents‑fleet to browse children, read their transcripts, steer them, or stop them.
A built‑in watchdog can monitor for adversarial changes, enforce LSP checks, and limit how many subagents a single run may spawn (maxSubagentSpawnsPerRun, default 64).
Helper commands:
- /subagents‑doctor – runs a health‑check on the subagent system.
- /subagents‑guide [topic] – shows documentation on topics such as workflows, agents, observability, etc.

Configuration

All settings live in a config.json (or environment variables). Important knobs include:

toolActivation – controls whether the subagent tool is loaded immediately or only after the model’s prompt cache is refreshed.
bg_wait – how long the parent waits for background children before reporting status.
maxSubagentSpawnsPerRun – caps the total logical children a single orchestration may create.

Full details are in the repository’s docs/ folder.

Who might benefit?

Developers who want AI‑assisted code reviews, automated implementation, or research without leaving their editor.
Teams that need reproducible, auditable AI workflows (e.g., “run a reviewer, then a worker, then another reviewer”).
Power users of the Pi platform looking to compose multiple specialized AI agents into a single, coherent pipeline.

Quick start checklist

Install the extension: pi install npm:pi-subagents.
In a Pi chat, type a natural‑language request like Use reviewer to review this diff.
Watch the result stream in the conversation or inspect the background fleet view.
Use /subagents‑guide to explore more advanced workflows and configuration options.

Bottom line: pi‑subagents turns a single Pi AI assistant into a tiny, orchestrated team of purpose‑built agents, making complex tasks—code review, research, implementation, auditing—easier to run, monitor, and repeat.