[Pi Series 4] Plugin basics: install, check, update, and remove packages

In pi, plugin-like features are usually installed as pi packages. A package can contain extensions, skills, prompt templates, and themes.

So before introducing useful packages, we need to cover the basic usage first. Even if you know which package is useful, you cannot use it comfortably until you know how to install, check, update, and remove it.

---

What this post covers

• Understand the pi install npm:... format
• Distinguish global and project-local installs
• Reload resources after installation
• Check installed packages
• Update and remove packages
• Understand the difference between .ts example files and npm packages

---

Basic install format

For a pi package published to npm, use this format:

pi install npm:package-name

For example, to install the resource center package:

pi install npm:pi-resource-center

If pi is already running, reload resources after installation.

/reload

You can also restart pi in a new terminal.

pi

---

Installing from GitHub

Packages can also be installed from GitHub repositories.

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

This is useful when you want to pin a specific tag or commit.

pi install git:github.com/user/[email protected]

When a ref is pinned, pi update will not unexpectedly move it to a newer version.

---

Global vs project-local installs

A plain pi install usually records the package in the user-level settings.

pi install npm:package-name

The global settings file is:

~/.pi/agent/settings.json

If you want the package only for the current project, add -l.

pi install npm:package-name -l

This writes to the project settings.

.pi/settings.json

Use this rule of thumb:

Scope	Command	When to use
Global	pi install npm:package	Features you use in every project
Project	pi install npm:package -l	Features needed only in the current repo

A question UI or resource browser can be global. Document parsing, web research, or internal provider integration may be better as project-local installs.

---

Checking installation

List installed packages with:

pi list

If a package adds slash commands, run those commands inside pi to check that it loaded.

Examples:

/resource
/ask-settings
/web-agent doctor
/docparser:doctor

If the command does not work, run /reload first.

/reload

If it still does not work, use pi list to check whether the package is installed.

---

Updating packages

To update pi and installed packages together, use:

pi update

To update only pi itself:

pi update --self

To update packages only:

pi update --extensions

To update one package:

pi update npm:pi-resource-center

After updating, reload resources or restart pi.

---

Removing packages

Remove a package you no longer use.

pi remove npm:package-name

Example:

pi remove npm:pi-resource-center

uninstall is also an alias for remove.

pi uninstall npm:pi-resource-center

After removal, reload or restart pi so the old resources disappear from the running session.

---

.ts files are not packages

The official pi examples include files such as:

permission-gate.ts
protected-paths.ts
preset.ts
notify.ts

These are extension example files, not npm package names. This is usually not a valid install command:

pi install npm:permission-gate.ts

A better order for real use is:

1. First look for a pi package published on npm or GitHub.
2. If it exists, install it with pi install npm:... or pi install git:....
3. If no package exists and only an example file is available, then consider copying or customizing it under .pi/extensions/.

For beginners and most users, steps 1 and 2 are enough. Copying .ts files directly belongs to the customization stage.

---

How to find packages

The easiest starting point is installing pi-resource-center.

pi install npm:pi-resource-center

Then open it inside pi.

/resource

You can open specific resource categories as well.

/resource packages
/resource extensions
/resource skills
/resource prompts
/resource themes

This browser lets you inspect and manage installed packages, extensions, skills, and prompts.

---

Security checklist

pi packages are convenient, but extensions may run with your user-level system permissions. Before installing a package, check at least the following:

• Is the package name and GitHub repository trustworthy?
• Does the README explain install and usage commands?
• Does it read or write files?
• Does it execute shell commands?
• Does it send network requests?
• Could it log API keys or tokens?
• Should it be global, or would a project-local install be safer?

Using pi lightly does not mean avoiding packages. It means installing the packages you need while understanding where they are installed and what permissions they have.

---

Summary

Purpose	Command
Install npm package	pi install npm:package
Install Git package	pi install git:github.com/user/repo@v1
Project-local install	pi install npm:package -l
List installed packages	pi list
Update all	pi update
Update pi itself	pi update --self
Remove package	pi remove npm:package
Reload resources	/reload

In the next post, we will use this basic flow to install practical pi packages by category.