pi-subagents

Give pi a dependable engineering team

pi-subagents turns delegation in pi into a complete workflow, not just a way to launch another prompt.

Your main agent can send research to explorer, implementation to worker, intentional cleanup and duplicate-code consolidation to cleaner, documentation synchronization to documenter, and independent checks to reviewer. Each role runs in its own child process with a clean context, works in the background, and returns its result automatically. Active top-level work can be steered or retargeted; managed stages can be parked, resumed, stopped, or forked without losing retained context.

You
 └─ pi main agent
     ├─ explorer ─── maps the codebase
     ├─ worker ───── implements ─┬─▶ documenter ─▶ reviewer
     ├─ cleaner ──── cleans up ──┘       (enabled roles only)
     ├─ documenter ─ synchronizes docs ─▶ reviewer
     └─ reviewer ─── advisory report (no VERDICT), or managed gate
          ├─ REVIEW_PASS + documenter → documenter → fresh reviewer
          └─ REVIEW_FAIL → worker → optional documenter → reviewer

The stable parent run returns one final result when the complete workflow settles.

Install it once and keep using pi normally. The extension teaches the main model when to delegate, so most users do not need custom prompts or manual orchestration.

Why use pi-subagents?

Use pi-subagents when delegation should remove coordination work, not create more of it.

• The right specialist gets the right job. Research, implementation, cleanup, and review have separate roles, tools, and operating rules.
• You do not babysit background work. Results wake the main agent automatically; there is no polling loop and no “go check whether it finished” step.
• Parallel edits stay safe. Parallel workers use temporary, isolated Git checkouts (worktrees) by default, then apply their changes back without touching your index.
• Documentation stops drifting. Enabled documenter runs automatically after successful workers/cleaners and before the final reviewer. It can also run an explicitly requested whole-codebase maintenance pass.
• Review can close the loop. A failed gate can automatically dispatch a worker, run documentation sync, request another independent review, and repeat up to a hard limit.
• Agents remain controllable. Every run has a stable id and retained session, so you can change direction or continue later without starting from zero.
• Failures are handled, not hidden. Model failures can hand the same session to the current main model; pre-prompt startup races retry safely; process and integration failures are reported with recovery details.

More than a basic sub-agent launcher

A basic launcher often gives you…	pi-subagents gives you…
One generic child role	Five focused engineering roles
A one-shot prompt	Retained, steerable, resumable, forkable threads
Concurrent writers in one checkout	Git worktree isolation for parallel workers
A review report you must act on manually	Automatic writer → documenter → reviewer delivery and bounded fix rounds
Manual polling or follow-up	Automatic result delivery that resumes the main agent
A hard failure when the selected model is unavailable	Direct handoff to the current main model
Synchronized retries during startup contention	Extended jittered backoff that reduces retry collisions

Quick start

Requires pi >= 0.83.0 and Node.js >= 22.19.0.

pi install npm:@ferris1225/pi-subagents

Open pi and run the setup wizard:

/subagents-setup

Fresh installs enable explorer, worker, cleaner, and reviewer. documenter is available in the wizard but stays off until you select it. You can keep the current main model for every role or choose a different model and thinking level per agent.

Then ask for work in plain language:

Map how authentication works, fix the refresh race, run the tests, and review the diff.

Clean up src/cache. Remove only code you can prove is dead, then verify the result.

Compare screenshots/settings.png with design.png and report every visual mismatch.

The main agent decides when delegation is useful. You can also call the tools explicitly when you want exact control.

What changed in 4.1.2

Documentation sync as a real workflow stage

The new documenter is a write-capable, explorer-class role with two modes:

1. Pre-commit diff sync — after the last code edit and before the final reviewer, it compares the actual diff with comments, README/docs, examples, commands, config, defaults, and lifecycle descriptions.
2. Whole-codebase maintenance — when explicitly requested, it scans an existing project for stale comments and documentation and applies every safe, verified correction in scope.

It never changes runtime behavior, commits, pushes, publishes, or bumps versions. When enabled, runtime now treats it as a managed stage: successful top-level worker/cleaner runs continue through documenter → reviewer, a successful whole-codebase documenter continues through reviewer, and auto-fix rounds use worker → documenter → reviewer. Existing non-empty configs receive documenter once and inherit the configured explorer model and thinking level; fresh installs leave it as an explicit setup choice.

Safer startup contention recovery

Startup contention is much harder to exhaust. A child that exits or fails its RPC readiness handshake before the initial prompt is dispatched is retried through a longer backoff window. Each default delay also gets additive jitter, reducing the chance that several children retry in the same lockstep waves. The base window covers stale startup locks and leaves headroom beyond the default four-way fan-out.

Only a failure known to precede prompt dispatch qualifies. Once the parent sends a prompt command, pi-subagents will not replay it—even if the ACK is lost or an idle watchdog wins the race—because Pi may already have started the model or tools. This recovery therefore cannot repeat model calls or edits.

Meet the team

Agent	Access	Best for
explorer	Read-only	Broad codebase search, unfamiliar-area mapping, symbol and dependency tracing, and multi-file reconnaissance.
worker	Full	A self-contained implementation, bug fix, refactor, or test task carried through verification.
cleaner	Full	Explicitly authorized cleanup, removal, simplification, and duplicate-code consolidation. Dispatch authorizes every safe in-scope cut; it must prove each one.
documenter	Docs/comments	Pre-commit diff sync or explicitly requested whole-codebase documentation maintenance. Uses an explorer-class model, may make zero edits, and never changes runtime behavior.
reviewer	Read-only	Audits, code-health checks, plans, PR or issue validation, documentation-drift checks, and fresh pre-commit gates.

Children have no memory of the parent conversation. A good manual brief includes the goal, exact paths, constraints, and expected output. The injected delegation guidance does this automatically when the main agent dispatches on your behalf.

Everyday workflows

Delegate one task

subagent({
  agent: "explorer",
  task: "Map the test setup. Report exact files, commands, and CI entry points.",
});

subagent({
  agent: "worker",
  task: "Fix the cache invalidation bug in src/cache, add regression tests, and run the relevant checks.",
});

Fan out independent work

subagent({
  tasks: [
    { agent: "explorer", task: "Trace model fallback from dispatch to completion." },
    { agent: "worker", task: "Add edge-case tests for config migration." },
  ],
});

Independent tasks run up to maxConcurrency (default 4). One parallel call may contain at most that many tasks and is rejected if it exceeds the limit. Accepted background work from separate calls waits in the shared queue when all slots are busy.

Run an independent quality gate

subagent({
  agent: "reviewer",
  task: "Gate the current diff for correctness, regressions, and missing tests.",
});

A gate reviewer ends with REVIEW_PASS or REVIEW_FAIL. A direct pass is not accepted as the final gate while documenter is enabled: runtime first syncs the actual pending diff, then starts a fresh reviewer. A failure uses the bounded loop:

reviewer → worker fixes every open finding → optional documenter sync → reviewer checks again → PASS/FAIL

Each step gets a fresh model context. The chain shares the same code state and passes every full reviewer, worker, and documenter report forward; it does not reuse one context window. Internal children bypass top-level lifecycle policy, so they cannot recursively start another chain.

maxFixRounds limits worker fix attempts only. Initial post-writer documentation and final review still run when it is 0. Generic audits and read-only reviews are advisory: they omit VERDICT, remain read-only, and never trigger edits.

Clean up without guessing

cleaner is only for requests that authorize cleanup edits. Once dispatched, that authorization covers every safe, proven in-scope cut without another item-by-item confirmation. It checks reachability, ownership, history, and boundaries before removing, simplifying, or consolidating anything, then verifies the result.

Repeated code is a first-class cleanup target. Cleaner compares contracts, invariants, side effects, ownership, and reasons to change—not just matching text—then extracts the smallest stable shared implementation and migrates all in-scope callers. It keeps similar code separate when domains or future change axes genuinely differ, avoiding a generic abstraction that is worse than the duplication.

explicit cleanup request → cleaner applies proven cuts → documenter syncs docs → reviewer gates the diff
read-only cleanup audit   → reviewer reports candidates only

This separation matters: asking for an audit does not silently authorize code changes, and asking for cleanup does not reward speculative deletion.

Keep comments and README/docs synchronized

documenter has two deliberate launch paths.

For a pending worker or cleaner change, enable the role. Runtime schedules it automatically against the actual diff before the final reviewer; do not dispatch a duplicate manual sync. If reviewer is disabled, documenter becomes the final managed stage. If documenter is disabled, reviewer follows the writer directly.

For an existing project, explicitly authorize a broad maintenance pass:

subagent({
  agent: "documenter",
  task: "Run a whole-codebase documentation maintenance pass. Verify comments, docstrings, README files, docs, and examples against the implementation; update every safe stale statement in scope.",
});

A successful explicit whole-codebase documenter also continues automatically to reviewer when enabled. A generic or read-only documentation audit still belongs to reviewer. documenter is the last writer, never the approver:

worker / cleaner / documenter / auto-fix worker → enabled downstream roles → one final delivery

Safe parallel editing

A Git worktree is a temporary second checkout of the same repository. It shares Git history with your main checkout but has its own files, so two workers do not overwrite each other while they run.

Every child has process and context isolation. Write-capable tasks can also have filesystem isolation:

• A single task defaults to isolation: "shared".
• Parallel worker tasks default to isolation: "worktree".
• cleaner and documenter support worktree mode when explicitly requested; their default remains shared.
• Read-only explorer and reviewer tasks reject worktree mode because they do not need a writable checkout.

Worktree mode requires a Git repository with a committed HEAD. For an isolated writer, automatic documenter/reviewer children run inside that same worktree. Those isolated stages can still run in parallel; writer and documentation changes are integrated only after the final reviewer settles. Tracked, deleted, untracked, and binary changes are then carried back to the original checkout without staging or modifying the parent index.

Repository-lane discovery uses the Git top-level even in an empty repository, so root and nested paths share one lane before the first commit. Every shared worker, cleaner, and documenter writer—and each shared reviewer snapshot when managed writers are enabled—uses that lane. Standalone documentation, writer-only configurations, and workflows without reviewer cannot race another writer or documentation sync. Isolated agents keep doing model work in parallel, but their final apply waits for the same lane.

Normal completion, stop, and shutdown share one finalization result, so isolated state is applied at most once. If park, stop, or shutdown wins after the top-level child settles, no downstream role starts and the stable top-level session remains the checkpoint. If setup or integration fails, pi-subagents keeps the useful patch or worktree when possible and records recovery information in:

~/.pi/agent/pi-subagents-recovery.json

A parked isolated thread keeps its worktree. Resume continues there. Forking an isolated checkpoint is available after that checkpoint has settled and integrated.

Follow, redirect, or stop a run

Dispatch confirmations and completion messages include a stable #id. That parent id represents the whole managed workflow; each internal documenter, reviewer, and fix step gets a separate queryable id in the final summary. No internal completion wakes the main agent.

Tool	What it does
subagent_control	steer, retarget, park, resume, or fork a logical thread.
subagent_status	Show active and recent runs, or return the full result for one id.
subagent_wait	Look up a result in the current turn. It is non-blocking by default; use timeoutMs only when you must wait in-turn.
subagent_stop	Destructively cancel work, deliver partial output, and retire that thread's retained session. Independent forks survive.

subagent_control({ action: "steer", id: 7, instruction: "Check the Windows path too." });
subagent_control({ action: "park", id: 7 });
subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
subagent_control({ action: "fork", id: 7, objective: "Try the smaller design instead." });

Use steer or retarget only while the top-level RPC child is active. During an automatic documenter, reviewer, or fix stage, use park or stop; park and then resume with a new objective when you need to redirect retained context. Use park to preserve the newest active stage and release its process slot; parking during documentation retains the documenter's partial/session, not an older writer or review. Use stop only when you want to discard that thread's future continuation. Stop and session shutdown abort the active internal stage, suppress stale delivery, and leave worktree finalization to the same one-time lifecycle owner. stop-all interrupts every lane holder before waiting for finalization, avoiding self-deadlock when an isolated apply is queued behind shared work.

Results and live status

The active TUI widget shows queued and running work as a compact tree:

● reviewer · review diff of src/cache.ts · claude-sonnet-4-5/high · 42s
  ├ ● worker · fix round 1 · src/cache.ts · claude-sonnet-4-5/high · 10s
  │    grep cacheKey
  ├ ● documenter · docs round 1 · claude-haiku-4-5/low · 4s
  └ ○ reviewer · re-review round 1 · claude-sonnet-4-5/high · 3s

Completed internal rows disappear from the widget; a parked parent remains queryable. Final messages contain one managed-workflow summary with aggregate token/cost totals and every internal id. Long output is truncated in the conversation and written to a temporary Markdown artifact; subagent_status keeps each complete run report available by id.

The main agent is told not to paraphrase a result you have already seen. It should add only its own conclusion or next action instead of charging you twice for the same explanation.

Models, thinking, and image work

Each agent can use the current main model or one selected in /subagents-setup. The setup picker shows authenticated models and labels them vision or text-only.

selected agent model → current main model

If the selected model is missing, unavailable, rate-limited, out of quota, or fails at the provider level, the current main model continues the same retained session. Searches, reads, reasoning, and edits already completed are preserved. Ordinary tool and test failures remain task failures and do not trigger a model handoff.

Thinking defaults to Auto. pi-subagents starts from the role's preference and chooses only a level the effective model actually supports. A fallback re-checks the level for the main model. documenter deliberately ships with the same fast, low-thinking profile as explorer; migration and manual enablement copy any configured explorer route, and you can still override it independently.

There is no separate vision mode. Assign a multimodal model to the agent and name the image paths in the task:

subagent({
  agent: "reviewer",
  task: "Compare screenshots/settings.png with design.png and list every visual mismatch.",
});

Reliability without duplicate work

• Startup recovery: silent, zero-activity failures before prompt dispatch retry with extended jittered backoff. A dispatched prompt is never replayed, even when its ACK is lost.
• Idle watchdog: a run with no RPC output for idleTimeoutSec is terminated; selected-model failures can continue on the current main model.
• Retained context: model handoff, park/resume, retarget, and fork build on the same session history instead of repeating discovery.
• Visible failures: process crashes, partial parallel starts, model failures, and Git integration failures are returned as failures rather than silent hangs.
• Safe status text: live tool activity is credential-redacted and stripped of terminal control characters.
• No runaway trees: child processes are leaves; they cannot dispatch more sub-agents.

Configuration

The wizard covers enabled agents, per-agent models and thinking, concurrency, auto-fix rounds, and the idle timeout:

/subagents-setup

Configuration is stored at ~/.pi/agent/pi-subagents.json and follows PI_CODING_AGENT_DIR when that environment variable is set.

{
  "enabledAgents": ["explorer", "worker", "cleaner", "documenter", "reviewer"],
  "agentModels": {
    "explorer": "anthropic/claude-haiku-4-5",
    "documenter": "anthropic/claude-haiku-4-5"
  },
  "agentThinkingLevels": {
    "documenter": "low",
    "reviewer": "high"
  },
  "notifyOnReviewPass": false,
  "maxResultLines": 80,
  "proactiveInjection": true,
  "agentScope": "user",
  "maxConcurrency": 4,
  "maxFixRounds": 2,
  "idleTimeoutSec": 90
}

Field	Meaning
enabledAgents	Agent names available for discovery and delegation. [] disables all agents.
agentModels	Optional provider/model-id per agent. Missing means use the current main model.
agentThinkingLevels	Optional manual level per agent. Missing means Auto.
notifyOnReviewPass	When true, a standalone passing gate is delivered without waking the main agent. Managed workflows still wake once at final delivery. Default false.
maxResultLines	Lines kept in a completion message before the full result moves to a temporary artifact. Default 80.
proactiveInjection	Teach the main model when and how to delegate. Default true.
agentScope	Discover user, project, or both agent directories. Default user.
maxConcurrency	Running process limit and maximum tasks in one parallel call, from 1 to 16. Default 4.
maxFixRounds	Maximum worker fixes after REVIEW_FAIL; each fix is followed by optional documenter and reviewer. 0 disables fixes but not initial post-writer docs/review. Default 2.
idleTimeoutSec	Seconds without RPC output before termination. 0 disables the watchdog. Default 90.

Invalid values fall back safely. Older configs are normalized automatically. The former built-in name explore migrates to explorer, and pre-cleaner non-empty agent lists receive cleaner once. Existing non-empty configs also receive documenter once, inserted before reviewer, with any configured explorer model and thinking copied across. Fresh installs do not enable documenter until the user selects it. Later deliberate disables are respected.

Custom and overridden agents

Built-ins ship in the package. You can add or replace agents with Markdown files:

• User agents: ~/.pi/agent/agents/
• Project agents: nearest .pi/agents/ directory in a trusted project
• Precedence: project overrides user, user overrides built-in

To replace a built-in, use the same filename and name. Optional frontmatter:

---
name: explorer
description: Fast read-only codebase reconnaissance
model: anthropic/claude-haiku-4-5
thinking: low
tools: read, bash
---

The Markdown body becomes the child's additional system prompt. Configuration chosen in /subagents-setup takes precedence over frontmatter defaults.

Development

npm install
npm run check
npm test

The package has no bundled runtime dependencies; it uses pi and TypeBox as peer packages. Source is split by responsibility: managed dispatch/workflow policy, retained thread lifecycle, RPC transport, worktree integration, completion delivery, tools, and TUI status.

License

MIT