pi-subagent-manager

Hierarchical, steerable subagent threads for pi

Packages

Package details

extension

Install pi-subagent-manager from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-subagent-manager
Package
pi-subagent-manager
Version
0.10.0
Published
Oct 5, 2026
Downloads
1,495/mo · 1,495/wk
Author
championswimmer
License
MIT
Types
extension
Size
530.4 KB
Dependencies
3 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

pi-subagent-manager

npm version npm downloads CI codecov

Subagents for pi: let your main conversation hand work to named, steerable helper agents — in parallel, nested, and resumable.

📜 Changelog

Install

Requires pi 0.99.2+. No build step.

pi install npm:pi-subagent-manager

For local development:

pi install /absolute/path/to/pi-subagent
# Or try it without installing:
pi -e ./src/index.ts

How it works

It combines ideas from two tools:

  • Like Claude Code subagents: each agent runs in its own session, with its own system prompt, model and tools, and hands back only its final answer. Agent types are Markdown files with frontmatter. The type says what job an agent does.
  • Like Codex: every running agent has a path, such as /root/fix-auth/review. The path says where it sits in the tree.

Type and path are independent. One reviewer type can run at /root/fix-auth/review and /root/docs-pass/review at the same time.

/root                          ← your main pi conversation
  /root/fix-auth               ← child: starts with a snapshot of /root
    /root/fix-auth/review      ← grandchild: snapshot of /root/fix-auth
/k                             ← independent root: no /root history

What a subagent can do

  • Finish — returns a final answer (not its whole transcript) to the parent.
  • Pause — hands back without an answer; resume it later.
  • Report progress — sends updates while it keeps working.
  • Be steered — the parent can send it more input, or resume it after it finishes.
  • Survive restarts — threads are saved with the main session and come back on /reload or pi --resume.

Bundled agents

Type Use it for
architect Plans, tradeoffs, coordinating other agents
coder Implementation, debugging, refactoring, frontend UI
researcher Source-backed codebase and web research
reviewer Finding real defects; suggests minimal fixes
tasker Small bounded jobs and quick repo lookups
writer Prose and editing

They inherit your current model until you set preferences. Details: docs/default-agents.md.

Commands

Command Opens
/agents Settings (mode, limits, model picking, tool filtering)
/agents types Agent-type browser and editor
/agents tree Fullscreen tree and read-only live watcher (/agents status is an alias)
/agents import Import agents from other subagent extensions
/agents reload Reload definitions and settings

A live Agents widget sits above the input box. Choose Full (the existing tree) or Minimal (colored status counts and running-agent token totals, plus the browser hint) under Status Widget in /agents settings. In the fullscreen tree, Enter watches an agent, Escape returns, and i opens existing thread actions. A status strip below the previews shows how many agents are running and Press ← to open subagent browser. Press Left at the start of the main draft to open it; normal cursor movement is unchanged. See live navigation for controls and compatibility.

Docs

Good to know

  • Tool policies are not a sandbox. Agents share your working directory and OS permissions.
  • Children can use your registered extension, MCP and web tools when Tool Filtering permits them. Skills are not automatically loaded; external tools share main-session resources/context.
  • Don't run multiple subagent extensions together — they clash on /agents.

License

MIT