Installing packages

Every extension, skill, prompt template, and theme in this guide is distributed as a Pi package. You add them with pi install.

The basics

pi install npm:pi-web-access          # from npm
pi install npm:@foo/[email protected]    # pinned version
pi install git:github.com/user/repo   # from git
pi install git:github.com/user/repo@v1  # pinned tag or commit

Other supported sources include full https://github.com/... URLs and ssh://[email protected]/.... Git installs accept an @ref for a tag or commit.

Manage installed packages with:

pi list                       # list installed packages
pi remove npm:@foo/pi-tools   # remove (alias: pi uninstall)
pi update                     # update Pi and all packages (skips pinned)
pi update --extensions        # update packages only
pi update npm:@foo/pi-tools   # update a single package
pi config                     # enable/disable extensions, skills, prompts, themes

Install scopes

Scope	Flag	Installs to	Use for
Global	(default)	`~/.pi/agent/npm/` or `~/.pi/agent/git/`	Tools you want everywhere
Project-local	`-l`	`.pi/npm/` or `.pi/git/`	Project-specific workflows

Skills, prompts, extensions, and themes are also auto-discovered from conventional directories — ~/.pi/agent/{skills,prompts,extensions,themes}/ (global) and .pi/{skills,prompts,extensions,themes}/ (project) — so you can drop a single file in without publishing a package.

After installing: reload

Inside an interactive session, apply newly installed or changed packages without restarting:

/reload

/reload re-reads keybindings, extensions, skills, prompts, and context files.

Pinning and updating git packages

Git @ref values are pinned to a tag or commit, and pi update skips pinned packages. To move a pinned package to a newer ref, reinstall it:

pi install git:github.com/user/repo@new-ref

Git packages install runtime dependencies with npm install --omit=dev, so a package’s runtime deps must be declared under dependencies (not devDependencies).

Offline and telemetry

--offline (or PI_OFFLINE=1) disables all startup network operations, including update checks and install telemetry.
PI_SKIP_VERSION_CHECK=1 disables only the version check.
Set enableInstallTelemetry: false in settings.json (or PI_TELEMETRY=0) to opt out of anonymous install/update pings.

Security: review before you install

Next step

Read Core concepts to understand the difference between the four customization layers, then dive into the capability guides.