17  Pi Packages

17.1 Overview

Pi packages are distributable bundles of Pi resources: extensions, skills, prompt templates, themes, and models. Packages can be installed from npm, git repositories, or local directories, making it easy to share Pi capabilities across projects and teams.

17.2 Install and Manage

17.2.1 Installing Packages

# Install from npm
pi install npm:@foo/bar@1.0.0
pi install npm:@foo/bar            # latest version

# Install from git
pi install git:github.com/user/repo@v1
pi install git:github.com/user/repo  # latest commit

# Install from local path
pi install /path/to/package

# Install project-local (not global)
pi install npm:@foo/bar -l

17.2.2 Removing Packages

# Remove by source
pi remove npm:@foo/bar
pi remove git:github.com/user/repo

# Remove project-local
pi remove npm:@foo/bar -l

17.2.3 Updating Packages

# Update Pi itself
pi update

# Update a specific package
pi update npm:@foo/bar

# Update all packages
pi update --all

# Update packages only (not Pi)
pi update --extensions

# Refresh model catalogs only
pi update --models

17.2.4 Listing Packages

pi list

Shows all installed packages with their sources, versions, and enabled/disabled state.

17.2.5 Configuring Package Resources

pi config

Opens an interactive configuration menu to enable or disable individual resources (extensions, skills, prompts, themes) provided by installed packages.

17.3 Package Sources

17.3.1 npm Packages

Install from the npm registry:

pi install npm:@scope/package-name
pi install npm:@scope/package-name@1.2.3

The package must have a package.json with a pi field describing its resources.

17.3.2 Git Packages

Install from any git repository:

pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1.0.0
pi install git:github.com/user/repo@main

Git packages are cloned and their dependencies are installed. By default, npm install --omit=dev is used. When npmCommand is configured, git packages use plain install for compatibility with wrappers.

17.3.3 Local Packages

Install from a local directory:

pi install /path/to/package
pi install ./my-package

The directory must contain a valid package.json with a pi field.

17.4 Creating Packages

17.4.1 Package Structure

my-pi-package/
├── package.json          # npm package metadata + pi config
├── README.md
├── extensions/
│   └── my-extension.ts   # Pi extensions
├── skills/
│   └── my-skill/
│       └── SKILL.md      # Pi skills
├── prompts/
│   └── review.md         # Pi prompt templates
├── themes/
│   └── my-theme.json     # Pi themes
└── models/
    └── providers.json    # Custom model definitions

17.4.2 package.json

{
  "name": "@myorg/pi-tools",
  "version": "1.0.0",
  "description": "Collection of Pi extensions and skills",
  "main": "extensions/index.ts",
  "dependencies": {
    "typebox": "^0.32.0"
  },
  "pi": {
    "extensions": [
      "extensions/*.ts"
    ],
    "skills": [
      "skills/*/"
    ],
    "prompts": [
      "prompts/*.md"
    ],
    "themes": [
      "themes/*.json"
    ],
    "models": [
      "models/*.json"
    ]
  }
}

17.4.3 The pi Field

The pi field in package.json declares which resources the package provides:

Field	Glob Pattern	Description
extensions	extensions/*.ts	TypeScript extension files
skills	skills/*/	Skill directories containing SKILL.md
prompts	prompts/*.md	Prompt template markdown files
themes	themes/*.json	Theme JSON files
models	models/*.json	Custom model/provider definitions

Glob patterns are resolved relative to the package root.

17.5 Dependencies

17.5.1 Runtime Dependencies

Runtime dependencies must be declared in dependencies in package.json. Package installation uses production installs (npm install --omit=dev) by default, so devDependencies are not available at runtime.

{
  "dependencies": {
    "typebox": "^0.32.0",
    "zod": "^3.22.0"
  }
}

17.5.2 Peer Dependencies

Pi’s core packages are available without explicit installation:

• @earendil-works/pi-coding-agent
• typebox
• @earendil-works/pi-ai
• @earendil-works/pi-tui

Do not list these as dependencies unless you need a specific version.

17.6 Filtering

17.6.1 Resource Filtering

Users can enable or disable individual resources from installed packages:

pi config

This opens an interactive menu showing all resources from all packages. Toggle resources on or off as needed. Disabled resources are not loaded by Pi.

17.6.2 Programmatic Filtering

Extensions can filter resources at load time via the resources_discover event:

pi.on("resources_discover", async (event, ctx) => {
  // Modify discovered resources
  // event.extensions, event.skills, event.prompts, event.themes
});

17.7 Enable/Disable Resources

17.7.1 Via CLI

pi config

17.7.2 Via settings.json

Package resources can be controlled in settings:

{
  "packages": [
    {
      "source": "npm:@foo/bar",
      "enabled": true,
      "resources": {
        "extensions": {
          "my-extension": true,
          "experimental-feature": false
        },
        "skills": {
          "my-skill": true
        }
      }
    }
  ]
}

17.8 Scope and Deduplication

17.8.1 Global vs Project-Local

• Global packages are installed to ~/.pi/agent/packages/ and available in all projects
• Project-local packages (installed with -l) are stored in .pi/packages/ and only available in that project

17.8.2 Deduplication

When the same package is installed both globally and project-locally:

1. The project-local version takes precedence
2. Resources from the global version are not loaded (for the same package name)

When two different packages provide resources with the same name:

1. The first-loaded package’s resource wins
2. A warning is displayed at startup
3. Use pi config to resolve conflicts manually

17.8.3 Load Order

Resources are loaded in this order:

1. Built-in resources
2. Global packages (alphabetical by package name)
3. Project-local packages (alphabetical by package name)
4. User/global extensions (~/.pi/agent/extensions/)
5. Project-local extensions (.pi/extensions/)
6. CLI extensions (-e)

Tip

Use pi --verbose to see the load order and any conflicts during startup.

17.9 Publishing Packages

17.9.1 To npm

cd my-pi-package
npm publish

Users can then install with:

pi install npm:@myorg/pi-tools

17.9.2 Via Git

Push to a public git repository. Users install with:

pi install git:github.com/myorg/pi-tools@v1.0.0

17.9.3 Versioning

Use semantic versioning for packages. Users can pin specific versions:

pi install npm:@myorg/pi-tools@1.2.3
pi install npm:@myorg/pi-tools@^1.0.0
pi install git:github.com/myorg/pi-tools@v2.0.0

Note

When publishing updates, increment the version in package.json. Users running pi update <source> will pick up the new version.