Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/earendil-works/pi/llms.txt

Use this file to discover all available pages before exploring further.

Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare its resources in package.json under the pi key, or Pi auto-discovers them from conventional directories.
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.

​
Installing packages

# npm packages
pi install npm:@foo/bar
pi install npm:@foo/bar@1.0.0    # pinned version

# git packages
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1   # tag or commit
pi install git:git@github.com:user/repo  # SSH shorthand
pi install git:git@github.com:user/repo@v1.0.0

# URL formats
pi install https://github.com/user/repo
pi install https://github.com/user/repo@v1
pi install ssh://git@github.com/user/repo
pi install ssh://git@github.com/user/repo@v1

# Local paths
pi install /absolute/path/to/package
pi install ./relative/path/to/package
By default, install writes to global settings (~/.pi/agent/settings.json). Use -l to write to project settings (.pi/settings.json) instead. Project settings can be shared with your team — Pi installs any missing packages automatically on startup. To try a package without installing it, use --extension or -e: 
pi -e npm:@foo/bar
pi -e git:github.com/user/repo
This installs to a temporary directory for the current run only.

​
Managing packages

# Remove
pi remove npm:@foo/bar
pi uninstall npm:@foo/bar          # alias for remove

# List installed packages
pi list

# Update
pi update                          # update Pi and all non-pinned packages
pi update --extensions             # update non-pinned packages only
pi update --self                   # update Pi only
pi update --self --force           # reinstall Pi even if already current
pi update npm:@foo/bar             # update one package

# Enable/disable resources from packages
pi config
Versioned npm specs (e.g. npm:@foo/bar@1.0.0) and git refs are pinned and skipped by pi update.

​
Creating a package

Add a pi key to package.json and include the pi-package keyword for discoverability: 
{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}
Paths are relative to the package root and support glob patterns and !exclusions. Without a pi manifest, Pi auto-discovers resources from conventional directories:
DirectoryLoads
extensions/.ts and .js files
skills/Directories with SKILL.md, top-level .md files
prompts/.md files
themes/.json files

​
Package structure example

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

​
Dependencies

Third-party runtime dependencies belong in dependencies in package.json. When Pi installs a package from npm or git, it runs npm install automatically. Pi bundles these core packages — list them in peerDependencies with "*" and do not bundle them:
  • @earendil-works/pi-ai
  • @earendil-works/pi-agent-core
  • @earendil-works/pi-coding-agent
  • @earendil-works/pi-tui
  • typebox
Other Pi packages must be bundled. Add them to both dependencies and bundledDependencies, then reference their resources via node_modules/ paths: 
{
  "dependencies": {
    "other-pi-package": "^1.0.0"
  },
  "bundledDependencies": ["other-pi-package"],
  "pi": {
    "extensions": [
      "extensions",
      "node_modules/other-pi-package/extensions"
    ]
  }
}

​
Project-local installs

Use the -l flag to install packages into project settings instead of global: 
pi install npm:@foo/bar -l     # writes to .pi/settings.json
pi remove npm:@foo/bar -l
Project settings are meant to be committed. Teammates get the same packages automatically when they open the project.

​
Package filtering

Control exactly which resources a package loads using the object form in settings.json: 
{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}
  • Omit a key to load all of that resource type.
  • Use [] to load none of that type.
  • !pattern excludes matches.
  • +path force-includes an exact path.
  • -path force-excludes an exact path.
Filters narrow down what the package manifest already allows.

​
npm configuration

If you use a Node version manager, pin npm to a specific context: 
{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
This applies to all npm installs and package lookup operations. The package gallery displays packages tagged with pi-package. Add video or image fields to show a preview: 
{
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}
Video takes precedence when both are set. Video autoplays on hover on desktop; clicking opens a fullscreen player.

Extensions

Write TypeScript extensions to include in your package.

Skills

Write skills to include in your package.

Prompt templates

Write prompt templates to include in your package.

Themes

Write themes to include in your package.

Build docs developers (and LLMs) love

Get started for freeTalk to us