@fitchmultz/pi-subagents

Pi extension for subagent orchestration and local session coordination

Packages

Package details

extensionskill

Install @fitchmultz/pi-subagents from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@fitchmultz/pi-subagents
Package
@fitchmultz/pi-subagents
Version
0.49.1
Published
Oct 15, 2026
Downloads
1,456/mo · 1,292/wk
Author
fitchmultz
License
MIT
Types
extension, skill
Size
7.4 MB
Dependencies
2 dependencies · 5 peers
Pi manifest JSON
{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./dist/extension/index.js",
    "./dist/pi-intercom/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-subagents

pi-subagents lets Pi delegate tasks to child sessions. Use it for code review, research, or implementation while you continue in the parent session.

A Pi parent session delegates independent tasks to scout and reviewer children, then receives their saved results.

Install and start

Requires Pi 1.0.0+ and Node 24.21.0+. Use macOS or Linux. Windows is not supported.

pi install npm:@fitchmultz/pi-subagents
pi

Enter a task in Pi:

Use scout to explain the authentication code in this project.

The built-in agents are ready to use. See the installation reference for Git installs and local checkouts.

Run tasks

Ask Pi for a child by role and task:

Have worker implement this approved plan, then ask reviewer to check the changes.

Children run in the background by default. You can also use commands:

Task Command
Review a diff /run reviewer "Review this diff"
Run parallel tasks /parallel scout "Inspect frontend" -> scout "Inspect backend"
Run a sequence /chain scout "Map auth" -> planner "Plan a refactor"
Run a saved workflow /run-chain scout-planner -- refactor authentication

Add --fg to wait for the result. The forceTopLevelAsync setting disables waits when enabled.

The saved workflow example requires a chain file named scout-planner. See the command reference for all options.

Choose a role and model

Task Built-in agents
Read code or gather evidence scout, context-builder, researcher
Plan or check a decision planner, oracle
Implement or repair a change worker, debugger, fixer, delegate
Review a change reviewer, reviewer-gpt, reviewer-claude, reviewer-security, reviewer-ponytail
Design, write or monitor ui-designer, writer, watcher

Ask Pi to show the effective profiles. Select an available model if a profile default is unavailable.

Model settings let you change a role without a copy of its agent file. Custom agents use ~/.pi/agent/agents/ or your project's .pi/agents/.

Read results and continue work

The Agents area shows active tasks and tasks that need attention. Open /agents to browse active and finished conversations.

The shortcut is Option+Shift+M on macOS and Alt+Shift+M elsewhere.

  • Open a conversation to read the child's report or send a message.
  • Press F2 to inspect details or request cancellation with Stop.
  • Select Continue to start follow-up work from a saved child session.
  • Press Esc to return to the parent session.

Resume the same saved parent session with pi --session /path/to/parent.jsonl to recover runs and questions.

See the conversation reference for shortcuts, drafts and history search.

Limits and warnings

Each child uses your provider account and can spend tokens. See usage accounting for details.

Children normally inherit Pi's tools, extensions, project instructions and skills. Restrict tools and project trust when a child must have limited access.

Intercom is included. It lets Pi sessions exchange messages and lets a child ask its parent for a decision.

Read the Intercom guide for setup and host limits. The secure bridge adds unattended remote messaging, durable inboxes, groups, live/saved session discovery, spawn/resume and native controls for an authenticated remote agent.

Indexed history requires SQLite 3.53.4 through Node's built-in node:sqlite binding. Other SQLite versions fail. See the storage requirements and host startup costs.

Update and troubleshoot

An update can leave active sessions on old code. Close all Pi sessions that use this installation before an update.

Run this command from a separate terminal:

pi update --extension npm:@fitchmultz/pi-subagents

Start new Pi processes after the update. /reload does not reliably activate changed JavaScript.

Run /subagents-doctor to check delegation and Intercom setup. See the installation reference for Git updates, local rebuilds and broker restarts.

Documentation

License

MIT.