Pi Packages

Pi packages bundle extensions, skills, prompt templates, and themes into installable packages shared via npm or git. PizzaPi inherits full support for pi’s package system — install community packages to extend your agent’s capabilities without writing code.

Installing Packages

From the terminal, use pizza install:

# From npm
pizza install npm:@foo/pi-tools
pizza install npm:@foo/pi-tools@1.2.3      # pinned version

# From git (multiple URL formats)
pizza install git:github.com/user/repo
pizza install git:github.com/user/repo@v1  # tag or commit
pizza install https://github.com/user/repo
pizza install ssh://git@github.com/user/repo

# From local path
pizza install /path/to/package
pizza install ./relative/path

By default, packages install globally (~/.pizzapi/settings.json). Use -l for project-local installs (.pizzapi/settings.json) — these can be shared with your team, and PizzaPi auto-installs missing packages on startup.

pizza list                    # Show installed packages
pizza update                  # Update all non-pinned npm packages
pizza remove npm:@foo/bar     # Remove a package
pizza config                  # Enable/disable specific resources

From a session or the web UI

Inside a session, /plugin package manages the same settings files:

/plugin package list
/plugin package install npm:@foo/pi-tools [--local]
/plugin package remove npm:@foo/pi-tools [--local]
/plugin package update [source]

--local targets the session’s project (.pizzapi/settings.json). Changes reload the session’s resources right away.

In the web UI, /plugins opens an interactive card with a Pi packages section (update, remove, and install, with an optional project-scope checkbox). The runner panel’s Plugins → Pi Packages tab offers the same controls at runner level. Use Apply to live sessions to reload the runner’s running sessions.

Package Sources

npm Packages

npm:@scope/package
npm:package@1.2.3

Global installs go into the managed prefix ~/.pizzapi/npm/
Project-local installs go under .pizzapi/npm/

If you use a Node version manager, set npmCommand in settings:

{ "npmCommand": ["mise", "exec", "node@20", "--", "npm"] }

Git Repositories

git:github.com/user/repo@v1
git:git@github.com:user/repo
https://github.com/user/repo@v1
ssh://git@github.com/user/repo

Cloned to ~/.pizzapi/git/<host>/<path> (global) or .pizzapi/git/<host>/<path> (project)
Runs npm install after clone/pull if package.json exists
SSH URLs use your configured SSH keys automatically

Package Filtering

Control which resources load from a package using the object form in settings:

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["themes/*.json"]
    }
  ]
}

Omit a key to load all of that type
Use [] to load none of that type
!pattern excludes matches

Use pizza config to interactively enable or disable resources from installed packages.

Finding Packages

Search npm: npm search keywords:pi-package
Check your package manager’s README for pi-package tagged repositories

Creating a Package

To create your own package, add a pi manifest to package.json:

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

Without a pi manifest, pi auto-discovers resources from conventional directories: extensions/, skills/, prompts/, themes/.

To additionally ship PizzaPi runner services, agents, rules, or MCP servers, add a pi.pizzapi overlay block — see Overlay Packages & the Extension SDK. The overlay is additive: vanilla pi ignores it, so one package works in both.

Package Structure

my-pi-package/
├── package.json           # With "pi" manifest
├── extensions/            # TypeScript extension files
│   └── my-extension.ts
├── skills/                # Skill directories with SKILL.md
│   └── my-skill/
│       └── SKILL.md
├── prompts/               # Prompt template .md files
│   └── review.md
└── themes/                # Theme .json files
    └── my-theme.json

Publishing

Publish to npm with the pi-package keyword for gallery visibility:

npm publish

Or share via a git repository — users install with:

pizza install git:github.com/you/my-pi-package