Skip to content
Maestria

Installation & Setup

@maestria/pi is a Pi extension that turns the Pi coding agent into a disciplined engineering workstation. It registers 7 specialist subagents, 3 workflow mode commands, and spec-driven orchestration - all with a single extension entry.

Prerequisites

Section titled “Prerequisites”
  • Pi CLI - the Pi coding agent (latest version)
  • Node.js 22.12+ - Required for npm-based extension resolution
  • @gotgenes/pi-subagents Pi extension - Required for subagent dispatch. Install with pi install npm:@gotgenes/pi-subagents
Section titled “Installation via maestria CLI (Recommended)”

The maestria CLI provides a unified interface for installing and managing maestria plugins across all supported platforms:

Terminal window
# Install for this platform
pnpx maestria@latest install pi


# Verify installation
pnpx maestria@latest status

The CLI automatically installs the @gotgenes/pi-subagents peer dependency (required for subagent dispatch) alongside the main extension.

Alternative: manual Pi CLI setup

If you prefer not to use the maestria CLI:

  1. Install the peer dependency:

    Terminal window
    pi install npm:@gotgenes/pi-subagents

  2. Install the extension:

    Terminal window
    pi install npm:@maestria/pi

  3. Restart Pi for both extensions to load.

Verify Installation

Section titled “Verify Installation”

Start a new Pi session. The @maestria/pi extension loads automatically from the package manifest. Pi’s resource loader discovers its four methodology skills (orchestrator dispatcher, global agent rules, handoff contract, iteration limits) from the pi.skills manifest field and injects them into the system prompt as <skill> blocks – the same standard mechanism used by all major Pi extensions.

You should notice Pi behaving as a maestria dispatcher from the first turn: it responds to requests by decomposing tasks, delegating to specialist subagents, and following the spec-driven orchestration protocol – all guided by the auto-injected orchestrator skill.

You can also list installed extensions to verify:

Terminal window
pi extensions list

You should see @maestria/pi in the output.

Updating

Section titled “Updating”

To update via the maestria CLI:

Terminal window
pnpx maestria@latest update pi
Alternative: Manual update

To update @maestria/pi to the latest version:

Terminal window
pi install npm:@maestria/pi@latest

Uninstalling

Section titled “Uninstalling”

Via maestria CLI

Section titled “Via maestria CLI”
Terminal window
pnpx maestria@latest uninstall pi

This removes @maestria/pi. The @gotgenes/pi-subagents peer dependency is left in place because other Pi extensions may depend on it.

Manual removal

Section titled “Manual removal”
  1. Remove from Pi config: edit ~/.config/pi/pi.json and remove "@maestria/pi" from the "extensions" array
  2. Uninstall:
    Terminal window
    pi uninstall @maestria/pi
  3. Optionally, remove @gotgenes/pi-subagents if no other extensions need it:
    Terminal window
    pi uninstall @gotgenes/pi-subagents
  4. Restart Pi

Next Steps

Section titled “Next Steps”