Install pi-subagentura

Install the Pi extension globally, for one project, or temporarily for one run. Interactive child sessions also need tmux, Zellij, or Herdr.

By lmn451 · Updated

Check the requirements

This guide covers the published pi-subagentura 4.2.1release; package metadata was verified 2026-11-07. Its Pi SDK peer packages (@earendil-works/pi-agent-core,@earendil-works/pi-ai, @earendil-works/pi-coding-agent, and @earendil-works/pi-tui) must be version 1.2.0 or newer. The typebox peer must be at least 1.1.38 and below 2; Node.js must be 22.23.2 or newer. See thev4.2.1 package.jsonor npm release metadata. Interactive subagents need a supported terminal multiplexer: tmux, Zellij, or Herdr. You can still install the extension without a multiplexer, but the interactive pane workflow needs one available.

The extension provides both interactive child sessions and lighter in-process delegation tools. This install guide focuses on getting the extension loaded; no Orchestratorv2 or workflow mode is required to begin.

Choose an install scope

Use the scope that matches how you work with Pi. The unversioned commands below select the latest npm release, which may be newer than this guide.

Install for all Pi projects

Run this once to make the extension available in your normal Pi sessions:

pi install npm:pi-subagentura

Install for the current project

From the project directory, use Pi’s local install option. This keeps the extension associated with that project rather than adding it to your global Pi setup.

pi install -l npm:pi-subagentura

Try it for one Pi run

To test the package without making a persistent install, launch Pi with the extension enabled for that run:

pi -e npm:pi-subagentura

To try the exact release documented here, specify its version:

pi -e npm:pi-subagentura@4.2.1

These commands install or load the extension. They do not automatically start a specialist. Once Pi is running, you can ask it to use an interactive subagent for a focused task.

Ask for one focused session

For a first check, try a small inspection request. This is an example prompt, not a claim that a session has already run:

Open one interactive specialist to inspect the project’s top-level structure.
Ask it to report the main application entry point and one relevant file.
Keep the session available so I can ask a follow-up.

The parent Pi agent decides how to handle the request. The extension also supports direct tool use and optional Orchestratorv2 routing; neither is required for the commands above. For the terminal setup and how to make a child pane visible, continue to the terminal sessions guide.

If it does not load

  • Confirm the Pi SDK peer packages are at least 1.2.0 and typebox is at least 1.1.38 and below 2.
  • Confirm Node.js is at least 22.23.2.
  • For interactive children, confirm tmux, Zellij, or Herdr is installed and available to the Pi process. A plain in-process delegation tool does not open a terminal pane.
  • If the request depends on current conversation details, include those details in the task or ask Pi to pass the parent context to the child. Interactive children otherwise have their own Pi session context.

See the product overview, thesession walkthrough, or thePi subagents overview. Next guides:tmux and Zellij sessionsand parallel code review.

Published package README· npm release details