Pi パッケージ

pi は pi パッケージを作成できます。ユースケース用のパッケージを構築するよう依頼してください。

Pi パッケージ

Pi パッケージは拡張、スキル、プロンプトテンプレート、テーマをバンドルし、npm または git 経由で共有できます。パッケージは package.json の pi キーでリソースを宣言するか、慣例ディレクトリを使用します。

インストールと管理

セキュリティ： Pi パッケージはフルシステムアクセスで実行されます。拡張は任意のコードを実行し、スキルはモデルに任意のアクション（実行ファイルの実行を含む）を指示できます。サードパーティパッケージをインストールする前にソースコードを確認してください。

pi install npm:@foo/[email protected]
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw URLs work too
pi install /absolute/path/to/package
pi install ./relative/path/to/package

pi remove npm:@foo/bar
pi list                     # show installed packages from settings
pi update                   # update pi only
pi update --all             # update pi, update packages, and reconcile pinned git refs
pi update --extensions      # update packages and reconcile pinned git refs only
pi update --self            # update pi only
pi update --self --force    # reinstall pi even if current
pi update npm:@foo/bar      # update one package
pi update --extension npm:@foo/bar

これらのコマンドは pi パッケージを管理し、pi update は pi CLI インストールも更新できます。pi 自体をアンインストールするには、クイックスタートを参照してください。

デフォルトでは install と remove はユーザー設定（~/.pi/agent/settings.json）に書き込みます。-l でプロジェクト設定（.pi/settings.json）に書き込みます。プロジェクト設定はチームと共有可能で、プロジェクトが信頼されると pi は起動時に不足パッケージを自動インストールします。

インストールせずに試すには --extension または -e を使用します。現在の実行のみ一時ディレクトリにインストールされます：

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

パッケージソース

Pi は設定と pi install で 3 種類のソースを受け付けます。

npm

npm:@scope/[email protected]
npm:pkg

バージョン付き spec は固定され、パッケージ更新（pi update --extensions、pi update --all）でスキップされます。
ユーザーインストールは ~/.pi/agent/npm/ 下。
プロジェクトインストールは .pi/npm/ 下。
settings.json で npmCommand を設定すると、mise や asdf など特定のラッパーコマンドに npm パッケージ検索とインストールを固定できます。

例：

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

git

git:github.com/user/repo@v1
git:[email protected]:user/repo@v1
https://github.com/user/repo@v1
ssh://[email protected]/user/repo@v1

git: プレフィックスなしではプロトコル URL のみ（https://、http://、ssh://、git://）。
git: プレフィックスありでは github.com/user/repo や [email protected]:user/repo などの短縮形式も可。
HTTPS と SSH URL の両方をサポート。
SSH URL は設定済み SSH キーを自動使用（~/.ssh/config を尊重）。
非対話実行（CI など）では GIT_TERMINAL_PROMPT=0 で認証プロンプトを無効化し、GIT_SSH_COMMAND（例：ssh -o BatchMode=yes -o ConnectTimeout=5）で高速失敗可能。
ref は固定 tag または commit。pi update --extensions と pi update --all は新 ref に移動しませんが、既存クローンを設定 ref に調整します。
pi install git:host/user/repo@new-ref で設定を更新し既存パッケージを新固定 ref に移動。
~/.pi/agent/git/<host>/<path>（グローバル）または .pi/git/<host>/<path>（プロジェクト）にクローン。
調整でチェックアウトが変わると、pi はクローンを reset/clean し、package.json があれば npm install を実行。

SSH 例：

# git@host:path shorthand (requires git: prefix)
pi install git:[email protected]:user/repo

# ssh:// protocol format
pi install ssh://[email protected]/user/repo

# With version ref
pi install git:[email protected]:user/[email protected]

ローカルパス

/absolute/path/to/package
./relative/path/to/package

ローカルパスはディスク上のファイルまたはディレクトリを指し、コピーせず設定に追加されます。相対パスは出現する設定ファイルに対して解決されます。パスがファイルなら単一拡張として、ディレクトリならパッケージルールでリソースを読み込みます。

Pi パッケージの作成

package.json に pi マニフェストを追加するか慣例ディレクトリを使用します。発見性のため pi-package キーワードを含めてください。

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

パスはパッケージルートからの相対パス。配列は glob パターンと !exclusions をサポート。

ギャラリーメタデータ

パッケージギャラリーは pi-package タグのパッケージを表示します。プレビュー用に video または image フィールドを追加：

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

video：MP4 のみ。デスクトップでホバー時自動再生。クリックで全画面プレイヤー。
image：PNG、JPEG、GIF、WebP。静的プレビューとして表示。

両方設定時は video が優先。

パッケージ構造

慣例ディレクトリ

pi マニフェストがない場合、pi はこれらのディレクトリから自動発見：

extensions/ は .ts と .js を読み込み
skills/ は SKILL.md フォルダを再帰検索し、トップレベル .md をスキルとして読み込み
prompts/ は .md を読み込み
themes/ は .json を読み込み

依存関係

サードパーティランタイム依存は package.json の dependencies に属します。拡張、スキル、プロンプトテンプレート、テーマを登録しない依存も dependencies に属します。pi が npm または git からパッケージをインストールすると npm install を実行するため、これらの依存は自動インストールされます。

Pi は拡張とスキル用にコアパッケージをバンドルします。以下をインポートする場合、peerDependencies に "*" 範囲でリストしバンドルしないでください：@earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent、@earendil-works/pi-tui、typebox。

他の pi パッケージは tarball にバンドルする必要があります。dependencies と bundledDependencies に追加し、node_modules/ パスでリソースを参照。Pi は独立モジュールルートでパッケージを読み込むため、別インストールは衝突やモジュール共有しません。

例：

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

パッケージフィルタリング

設定のオブジェクト形式でパッケージの読み込み内容をフィルタ：

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

+path と -path はパッケージルートからの正確なパス。

キーを省略するとそのタイプをすべて読み込み。
[] でそのタイプを一切読み込まない。
!pattern で一致を除外。
+path で正確なパスを強制包含。
-path で正確なパスを強制除外。
フィルターはマニフェストの上に重なり、既に許可された内容を絞り込み。

リソースの有効化と無効化

pi config でインストール済みパッケージとローカルディレクトリから拡張、スキル、プロンプトテンプレート、テーマを有効/無効化。グローバル（~/.pi/agent）とプロジェクト（.pi/）スコープの両方で動作。

スコープと重複排除

パッケージはグローバルとプロジェクト設定の両方に現れます。同じパッケージが両方にある場合、プロジェクトエントリが優先。同一性は以下で決定：

npm：パッケージ名
git：ref なしのリポジトリ URL
local：解決済み絶対パス

Pi パッケージ

Pi パッケージ

目次

インストールと管理

パッケージソース

npm

git

ローカルパス

Pi パッケージの作成

ギャラリーメタデータ

パッケージ構造

慣例ディレクトリ

依存関係

パッケージフィルタリング

リソースの有効化と無効化

スコープと重複排除