Packages (npm/git)

✓ Fresh · 2026-02-24

Pi packages bundle and distribute extensions, skills, prompts, and themes via npm or git. This is the primary mechanism for sharing Pi customizations with others.

Installing Packages

From npm

# Latest version
pi install npm:@foo/pi-tools

# Pinned version (skipped during `pi update`)
pi install npm:@foo/pi-tools@1.2.3

From git

# Latest
pi install git:github.com/user/repo

# Tagged version
pi install git:github.com/user/repo@v1

Project-Local Installation

Use -l to install into the project directory instead of globally:

pi install -l npm:@foo/pi-tools

Flag	Install Location
(default)	~/.pi/agent/npm/ or ~/.pi/agent/git/
-l	.pi/npm/ or .pi/git/

Managing Packages

# List all installed packages
pi list

# Update all packages (skips pinned versions)
pi update

# Remove a package
pi remove npm:@foo/pi-tools

# Configure which resources are enabled/disabled
pi config

Package Lifecycle

Creating a Package

Package Structure

A Pi package is a standard npm package with a pi field in package.json:

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

Directory Layout

my-pi-package/
├── package.json
├── extensions/
│   ├── my-tool.ts
│   └── my-command.ts
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── prompts/
│   ├── review.md
│   └── test.md
└── themes/
    └── ocean.json

Auto-Discovery

Pi can auto-discover resources from conventional directory names without an explicit pi field in package.json. If your package has an extensions/, skills/, prompts/, or themes/ directory, Pi finds them automatically.

Publishing

Publish to npm like any other package:

npm publish

Or push to a git repository for git-based installation.

Security Warning

SECURITY

Pi packages run with full system access. They can:

• Execute arbitrary code
• Read and write any file
• Make network requests
• Access environment variables (including API keys)

Always review the source code of a package before installing it. Only install packages from sources you trust.

Package vs Manual Installation

Approach	Pros	Cons
Pi packages	Easy install/update/remove, shareable, versioned	Need to publish to npm/git
Manual files	Full control, no publishing needed	Manual updates, not easily shareable

For personal extensions, manual files in ~/.pi/agent/extensions/ work fine. For sharing with a team or the community, packages are the way to go.