Pi Packages

Pi can help you create pi packages. Just ask it to bundle your extensions, skills, prompt templates, or themes.

Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in package.json under the pi key, or use conventional directories.

Installing Packages

Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.

npm
git (HTTPS)
git (SSH)
Local Path

# Latest version
pi install npm:@foo/bar

# Specific version (pinned, skipped by update)
pi install npm:@foo/bar@1.0.0

# GitHub shorthand
pi install git:github.com/user/repo

# Full HTTPS URL
pi install https://github.com/user/repo

# With tag/commit (pinned)
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo@v1.0.0

# git@host:path shorthand (requires git: prefix)
pi install git:git@github.com:user/repo

# ssh:// protocol
pi install ssh://git@github.com/user/repo

# With tag/commit (pinned)
pi install git:git@github.com:user/repo@v1.0.0

Uses your configured SSH keys (respects ~/.ssh/config).

# Absolute path
pi install /absolute/path/to/package

# Relative path
pi install ./relative/path/to/package

Not copied - added as reference.

Global vs Project Install

By default, packages install globally (written to ~/.pi/agent/settings.json). Use -l for project install (written to .pi/settings.json):

pi install -l npm:@foo/bar

Project packages:

Can be shared with your team
Auto-install on startup if missing
Override global packages

Trying Without Installing

Test a package without installing:

pi -e npm:@foo/bar
pi -e git:github.com/user/repo

Installs to a temporary directory for the current run only.

Managing Packages

List
Update
Remove
Configure

pi list

Shows all installed packages from settings.

# Update all non-pinned packages
pi update

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

Skips packages with version specifiers.

pi remove npm:@foo/bar
pi remove -l npm:@foo/bar  # From project settings

pi config

Enable/disable extensions, skills, prompts, and themes from installed packages.

Creating a Pi Package

Add a pi manifest to package.json or use conventional directories. Include the pi-package keyword for discoverability.

Basic Package

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

Directory structure:

my-package/
├── package.json
├── extensions/
│   ├── deploy.ts
│   └── monitor.ts
├── skills/
│   ├── web-search/
│   │   └── SKILL.md
│   └── transcribe/
│       └── SKILL.md
├── prompts/
│   ├── review.md
│   └── test.md
└── themes/
    ├── nord.json
    └── tokyo-night.json

Convention Directories

If no pi manifest is present, Pi auto-discovers resources:

extensions/ - .ts and .js files
skills/ - Recursively finds SKILL.md folders and top-level .md files
prompts/ - .md files
themes/ - .json files

Gallery Metadata

The package gallery displays packages tagged with pi-package. Add video or image for preview:

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

video: MP4 only. Autoplays on hover (desktop), clicking opens fullscreen
image: PNG, JPEG, GIF, or WebP static preview

If both are set, video takes precedence.

Package Structure

Single Type Package

Packages can contain just one type of resource:

{
  "name": "pi-deploy",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./src"]
  }
}

Glob Patterns

Arrays support glob patterns and exclusions:

{
  "pi": {
    "extensions": [
      "extensions/*.ts",
      "!extensions/disabled.ts",
      "+extensions/legacy.ts",
      "-extensions/broken.ts"
    ]
  }
}

pattern - Glob match
!pattern - Exclude matches
+path - Force-include exact path
-path - Force-exclude exact path

Dependencies

Runtime Dependencies

Third-party runtime dependencies belong in dependencies:

{
  "dependencies": {
    "axios": "^1.6.0",
    "cheerio": "^1.0.0"
  }
}

When Pi installs from npm or git, it runs npm install automatically.

Peer Dependencies

Pi bundles core packages. List them in peerDependencies with "*" range and do not bundle them:

{
  "peerDependencies": {
    "@mariozechner/pi-ai": "*",
    "@mariozechner/pi-agent-core": "*",
    "@mariozechner/pi-coding-agent": "*",
    "@mariozechner/pi-tui": "*",
    "@sinclair/typebox": "*"
  }
}

Bundled Dependencies

Other pi packages must be bundled. Add them to dependencies and bundledDependencies:

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "pi": {
    "extensions": [
      "extensions",
      "node_modules/shitty-extensions/extensions"
    ],
    "skills": [
      "skills",
      "node_modules/shitty-extensions/skills"
    ]
  }
}

Package Filtering

Users can filter what a package loads:

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

Rules:

Omit a key to load all of that type
Use [] to load none of that type
!pattern excludes matches
+path force-includes an exact path
-path force-excludes an exact path
Filters layer on top of the manifest (they narrow down what’s allowed)

Publishing

Prepare Package

Ensure:

package.json has pi manifest
keywords includes "pi-package"
All resources are included
Dependencies are declared

Test Locally

pi -e ./path/to/package

Publish

npm:

npm publish

git:

git tag v1.0.0
git push origin v1.0.0

Users Install

pi install npm:my-package
pi install git:github.com/user/my-package@v1.0.0

Scope and Deduplication

Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:

npm: package name
git: repository URL (without ref)
local: resolved absolute path

Example Packages

pi-skills

Official skills: web search, browser, transcription, Google APIs

Package Gallery

Browse community packages

Best Practices

Keep packages focused

Create separate packages for different purposes:

my-web-tools - Web scraping extensions
my-themes - Theme collection
my-ai-skills - AI/ML skills

This makes it easier for users to install only what they need.

Document everything

Include a comprehensive README with:

What the package provides
How to install
Usage examples
Configuration options
Screenshots/demos

Version carefully

Follow semantic versioning:

Patch (1.0.1): Bug fixes, documentation
Minor (1.1.0): New features, backward compatible
Major (2.0.0): Breaking changes

Test before publishing

Test locally with:

pi -e ./path/to/package

Verify:

All resources load
Extensions work
Skills execute
Themes display correctly

Add gallery media

Include video or image in the manifest to make your package stand out in the gallery.

Declare dependencies correctly

Runtime deps in dependencies
Pi packages in peerDependencies (core) or bundledDependencies (other)
Dev deps in devDependencies

Advanced Topics

Multi-Package Projects

For monorepos with multiple pi packages:

{
  "workspaces": ["packages/*"],
  "pi": {
    "extensions": [
      "packages/*/extensions"
    ],
    "skills": [
      "packages/*/skills"
    ]
  }
}

Private Packages

For private npm registries or git repositories:

# npm with private registry
pi install npm:@myorg/private-package

# Private GitHub repo (requires SSH key)
pi install git:git@github.com:myorg/private-repo

# GitLab
pi install git:git@gitlab.com:myorg/private-repo

Ensure you’re authenticated with the registry/service.

Offline Use

For environments without internet:

Install packages on a connected machine
Copy the package directories:
- npm global: npm root -g
- npm local: .pi/npm/
- git global: ~/.pi/agent/git/
- git local: .pi/git/
Transfer to offline machine

Use local path installs:

pi install ./copied-packages/my-package

Troubleshooting

Package not loading

Check:

Package is in pi list
Resources are enabled in pi config
Paths in manifest are correct
JSON is valid
npm install ran (for git packages)

git clone fails

For SSH:

Verify SSH key is added: ssh -T git@github.com
Check ~/.ssh/config for host aliases
Use HTTPS instead if SSH is problematic

Update doesn't fetch latest

Pinned packages (with version/tag) are skipped by pi update. Remove the pin:

pi remove npm:@foo/bar@1.0.0
pi install npm:@foo/bar
pi update

Dependency conflicts

If dependencies conflict between packages:

Check if they’re peer dependencies (should use Pi’s bundled version)
Consider bundling dependencies in one package
Report incompatibility to package authors

Next Steps

Extensions

Build TypeScript extensions

Skills

Create Agent Skills

Prompt Templates

Make reusable prompts

Themes

Design custom themes

Package Gallery

Browse existing packages

GitHub

View source & examples

Documentation Index

​Installing Packages

​Global vs Project Install

​Trying Without Installing

​Managing Packages

​Creating a Pi Package

​Basic Package

​Convention Directories

​Gallery Metadata

​Package Structure

​Single Type Package

​Glob Patterns

​Dependencies

​Runtime Dependencies

​Peer Dependencies

​Bundled Dependencies

​Package Filtering

​Publishing

​Scope and Deduplication

​Example Packages

pi-skills

Package Gallery

​Best Practices

​Advanced Topics

​Multi-Package Projects

​Private Packages

​Offline Use

​Troubleshooting

​Next Steps

Extensions

Skills

Prompt Templates

Themes

Package Gallery

GitHub

Installing Packages

Global vs Project Install

Trying Without Installing

Managing Packages

Creating a Pi Package

Basic Package

Convention Directories

Gallery Metadata

Package Structure

Single Type Package

Glob Patterns

Dependencies

Runtime Dependencies

Peer Dependencies

Bundled Dependencies

Package Filtering

Publishing

Scope and Deduplication

Example Packages

Best Practices

Advanced Topics

Multi-Package Projects

Private Packages

Offline Use

Troubleshooting

Next Steps