pi-dev-rules

Pi 開発ルール

Pi は最小限のターミナル用コーディングハーネスです。軽量なコアを備え、TypeScript によるカスタマイズで拡張できます。パッケージ：@earendil-works/pi-coding-agent。Earendil Inc. によって保守されています（MIT）。 このスキルは、https://pi.dev/docs/latest にある公式ドキュメントを反映しているため、Pi に関する質問に答えたり、情報を再取得せずに Pi のカスタマイズを構築したりできます。さらに、pi.dev のドキュメントサイトにはない情報を扱う 5 つのバンドルがあります。内部モノレポアーキテクチャ（Chord 型ホストランタイム、Pico5 仕様を備えた永続的なエージェントハーネス、エージェントコア、テレメトリー）、2026-10-01 の Earendil ブログ記事をもとに編集した Pi Durable の概要（実験的なハーネスとは何か、そのバージョン履歴、1.2.0 で削除されたブログのデモ）、そしてリポジトリ独自の開発・貢献ルールです。

このスキルを使う場面

• Pi のインストール、認証、起動、CLI フラグやスラッシュコマンドの説明。
• プロバイダー、API キー、カスタムモデル（models.json）、プロキシの設定。
• settings.json、キー割り当て、テーマの編集、セッションとコンパクションの理解。
• プロジェクト信頼セキュリティモデルの理解、およびコンテナやサンドボックスでの Pi の実行。
• Pi の拡張：拡張機能、スキル、プロンプトテンプレート、パッケージ、カスタムプロバイダー、TUI UI の作成、codemode の有効化やスクリプトの作成。
• Pi のバージョン履歴や、最近のリリースでの変更点の確認。
• SDK、RPC モード、JSON イベントストリームモードを介したプログラムによる Pi の操作。
• Windows／Termux／tmux／特定のターミナルでの Pi のセットアップ、またはソースからのビルド。
• Pi がこのように設計されている理由の理解：開発者の理念（最小限のコア、4 つのツール、デフォルトで YOLO。2025-11-30 のマニフェストでは、MCP、プランモード、ToDo、サブエージェントを意図的に搭載しない機能として挙げています。組み込み MCP は後の 2026-09-29 に導入されました）と、その理念に沿って Pi を設定・拡張する方法。
• pi モノレポ内部での作業：@earendil-works/chord 型ホストランタイム（コントラクト、ホストとリンク、ホットリロード、差分／複製状態）、永続的なハーネス（@earendil-works/pi-durable、Pico5）、エージェントコア、テレメトリー。実験的な server／client／protocol パッケージは 1.2.0 で削除されました。
• Pi Durable（@earendil-works/pi-durable）に関する開発や質問：ハーネスとは何か、各バージョンで何がリリースされたか、実行可能なサンプルの場所、ブログ記事のデモへのパスが存在しなくなった理由。

参照インデックス：必要なファイルを読み込む

ファイル	内容
references/cli-and-usage.md	インストール、認証、起動方法、Pi の仕組み（エージェントループ、コンテキストの組み立て、セッションツリー）、CLI の全リファレンス（コマンド、フラグ、モード）、スラッシュコマンド、メッセージキュー、コンテキストファイル、環境変数（bash-tool の PI_SESSION_*／PI_MODEL を含む）、セッション、キーバインド
references/providers-and-models.md	サブスクリプションおよび API キーを使用するプロバイダー（30 以上）、llama.cpp ローカルルーター、NVIDIA RTX レシピプリセット、auth.json（スコープ付き env を含む）、クラウドプロバイダー（Azure／Bedrock／Vertex／Cloudflare）、models.json のカスタムモデル、compat、カスタムプロバイダー拡張機能
references/settings-and-compaction.md	設定の構成（エージェントディレクトリとプロジェクト .pi/、コンテキストファイル）、settings.json のスキーマと例、信頼／分析／再試行／トランスポートのキー、圧縮（自動／手動）とブランチの要約
references/extending-pi.md	拡張機能 API（イベント、ツール、コマンド、UI）、スキル（SKILL.md）、プロンプトテンプレート、テーマ、パッケージ、仮想モデル（pi.registerVirtualModel）
references/mcp.md	組み込み MCP サポート（2026-09-29）：グローバルおよびプロジェクトのサーバー用 mcp.json、stdio とストリーム可能な HTTP、pi mcp add/remove/list、OAuth サインイン、toolExposure による公開モード（codemode、codemode-deferred、deferred、direct、hidden）、codemode／tool_search ツール、リソース、権限、拡張機能からのサーバー、SDK の配線、--no-mcp／mcp__* ツールのパターン
references/codemode.md	codemode ツール：スクリプト入力と // @options: 行、グローバル（tools.<name>()、text()、image()、console.log()、store()／load()、searchTools()、describeTool()）、ツール呼び出しの解決結果、分類器と画像モデル、名前空間とインライン予算、制限
references/tui-components.md	カスタム拡張機能／ツール UI 向けの TUI コンポーネントシステム（コンポーネント、オーバーレイ、テーマ設定、カスタムエディター）
references/security-and-containerization.md	プロジェクトの信頼モデル（trust.json、defaultProjectTrust）、組み込みサンドボックスなし、Gondolin マイクロ VM、Docker、OpenShell、Docker サンドボックス
references/session-format.md	セッション JSONL スキーマ：バージョン、コンテンツブロック、エントリー型、ツリー／コンテキストの構築、SessionManager API、およびモデル向けメッセージ型
references/programmatic.md	SDK、CLI 統合（インタラクティブ／印字／JSON／RPC モードの選択、RpcClient、フォークとリブランド）、JSON イベントストリームモード、RPC プロトコル、RPC コマンドリファレンス、RPC 拡張機能 UI
references/platform-setup.md	Windows、Termux、tmux、ターミナルごとの変更済み Enter キーの設定、シェルエイリアス
references/development.md	モノレポのパッケージ一覧、ソースからのビルドとスタンドアロンバイナリのビルド、サプライチェーンのルール、開発向け AGENTS.md ルール、CONTRIBUTING.md の必須手順
references/philosophy-and-design.md	作者 Mario Zechner の設計マニフェスト（ブログ、2025-11-30；手動で編集され、自動生成ではありません）：1000 トークン未満の最小限のプロンプト、4 つのツール、デフォルトで YOLO、記載されている非機能（MCP／計画モード／ToDo／サブエージェント／バックグラウンド bash）と、それぞれの想定代替手段、および 2026-09-29 以降に置き換えられたことが注記された MCP の項目、マルチプロバイダーアーキテクチャ、Terminal-Bench 2.0 の結果
references/chord.md	@earendil-works/chord：型付きホストランタイム（コントラクト、宣言、レジストリ、プリンシパル、ハンドル、ホットリロード）、ホストとリンク（memoryLinkPair、ipcLink、webSocketLink）、および chord/delta の複製された最新値状態。packages/chord/{README.md,docs/{guide,spec,tutorial}.md,src/delta/README.md} を基に構成。Pi Durable は Chord を使用しますが、Pi コーディングエージェントは使用しません。仕様には現在のランタイムが記載されています
references/durable.md	Pi Durable の概要。2026-10-01 の Earendil ブログ投稿と v1.3.0 のツリーを基に編集：ハーネス／会話／エージェント／タスク／実行環境の用語、位置付け（Pi CLI ではなく、エージェント型アプリケーションを構築するためのハーネス）、バージョンの推移（Pi 1.0 とともに 1.0.0 → 1.3.0、バージョンの同期、破壊的変更）、インストールとコード構成、パッケージ構成と実行可能な 32 の例、1.2.0 で削除されたブログのデモ。ステータスと参照先の確認は、まずこちらをご覧ください
references/agent-harness.md	内部ランタイムパッケージ：@earendil-works/pi-durable（永続的な会話／タスク／ドキュメントのハーネス、実験的な API、表示前に保存）、@earendil-works/pi-agent-core（ツール呼び出しと状態）、@earendil-works/pi-telemetry（ベンダー中立のテレメトリーコントラクト、アダプター、型付きスキーマ）。3 つのパッケージ README を基に構成。ユーザー向けドキュメントではなく、入口は durable.md です
references/durable-spec.md	pi-durable の規範的な Pico5 仕様（5352 行）：レコードとライフタイム、ドキュメントと変更の所有権、タスクとエフェクトサンドイッチ、送信と受信箱、拡張機能／フック／ツール、テレメトリー。実験的なパッケージの設計ドキュメントであり、固定された API ではありません。付属のテキストは v1.3.0 の仕様です
references/changelog.md	リリース履歴：直近 25 バージョンの主な変更点を packages/coding-agent/CHANGELOG.md から抽出（リリースセクションは 289 件。全文はチェックアウト内のファイルをご覧ください）

Pi 1.3.0 アップデートノート

• sessionShareDestination では、/share の送信先として auto、gist、radius を選択できます。
• 再開したセッションでは、アクティブなツールが復元されます。--tools +name／-name でそのセットを調整できます。
• --model の候補が曖昧な場合、認証情報があるプロバイダーが優先されます。それ以外の場合は、--provider を指定してください。
• Kimi Code は現在 Chat Completions を使用します。カスタムベース URL には /v1 を含める必要があります。
• Codemode では、キャンセル済みでも終了するまで稼働中として数え、Pi プロセスあたり最大 2 つのワーカーを実行できます。
• Pi Durable は SQLite のテーブルプレフィックスと、Cloudflare アダプターキューの共有に対応しています。

スタータープラグイン

すべての Pi ユーザーは、次の 3 つをインストールしてください（同じ作者による、実績のあるプラグインです）。

pi install npm:pi-subagents       # subagents / loop / chain / parallel
pi install npm:pi-lens            # real-time LSP diagnostics
pi install npm:pi-web-access      # web search, URL fetch, YouTube, PDF

次に pi list を実行して確認し、Pi を再起動してください。MCP はパッケージ不要です。2026-09-29 以降、組み込みで利用できます（references/mcp.md を参照）。 pi-mcp-adapter などの /mcp を登録するエクステンションを使うと、組み込みサポートに追加されるのではなく、置き換えられます。

チートシート

curl -fsSL https://pi.dev/install.sh | sh                         # install (pins dependencies)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent   # npm alternative (no pinned transitive deps)
export ANTHROPIC_API_KEY=sk-ant-...                               # or run /login in-session
cd /path/to/project && pi                                          # start interactive (may prompt to trust the project)

pi update                                 # update Pi itself (pi update self / pi update --self are aliases)
pi list                                   # list installed packages
pi -c                       # continue most recent session
pi -r                       # browse/resume sessions
pi --session <path|id>      # open specific session
pi --fork <path|id>         # fork a session
pi --no-session             # ephemeral (no save)
pi -a / -na                 # trust / don't trust project-local files for this run

pi -p "Summarize this codebase"                 # print mode (non-interactive)
pi @README.md "Summarize this"                  # attach files/images with @
cat file | pi -p "..."                          # pipe stdin
pi --provider openai --model gpt-4o "..."       # pick provider/model
pi --model sonnet:high "..."                    # model:thinkingLevel
pi --tools read,grep,find,ls -p "..."           # allowlist tools (-xt excludes; +name/-name adjusts defaults)
pi --mode json "..." | jq -c 'select(.type=="message_end")'   # JSON stream
pi --mode rpc                                   # JSON-RPC over stdin/stdout

# In-editor: @file (fuzzy), !cmd (run+send), !!cmd (run, hidden), /command, Ctrl+L model, Shift+Tab thinking, Ctrl+X copy
# While the agent runs: Enter queues a steering msg, Alt+Enter a follow-up, Esc aborts + restores

主な場所（グローバル ~/.pi/agent/、プロジェクト .pi/）： settings.json、auth.json、models.json、keybindings.json、trust.json、AGENTS.md、 SYSTEM.md、extensions/、skills/、prompts/、themes/、sessions/。

厳守事項

• インストールするパッケージ名は必ず @earendil-works/pi-coding-agent です。pi.dev インストーラー （curl -fsSL https://pi.dev/install.sh | sh）は依存関係を固定する、ドキュメントに記載されたインストール 方法です。グローバル npm インストールでは --ignore-scripts が必要で、依存関係は固定されません。
• プロジェクトのコンテキストファイルは AGENTS.md です（Pi は CLAUDE.md も読み込みます）。プロジェクトのルートに配置してください。
• 拡張機能はシステムの全権限で実行されます。信頼できるコードとして扱い、危険な 操作（rm、sudo、機密性の高いパス）は ctx.ui.confirm または tool_call ブロックハンドラーで制御してください。
• プロジェクトの信頼設定は入力読み込みのガードであり、サンドボックスではありません。 Pi には組み込みのサンドボックスはありません。プロジェクトを「信頼済み」とするのは、その .pi/ リソース（設定／拡張機能／スキル／プロンプト／テーマ）を読み込むかどうかを判断するためだけです。判断は ~/.pi/agent/trust.json に保存され、defaultProjectTrust （ask／always／never）によって制御され、実行ごとに --approve／--no-approve で上書きできます。信頼できないリポジトリや無人実行では、コンテナー／VM（Gondolin／Docker／OpenShell）で分離してください。サンドボックスからホストの認証情報を参照させる必要がない限り、ホストの ~/.pi/agent をマウントしないでください。
• MCP は 2026-09-29 から組み込みで利用でき、~/.pi/agent/mcp.json またはプロジェクトの .pi/ mcp.json で設定します。stdio サーバーはコマンドを実行するため、プロジェクトのファイルはプロジェクトが信頼済みになった後にのみ読み込まれます。MCP 呼び出しはツールパイプラインを経由するため、tool_call ハンドラーと権限ゲートが適用されます（codemode 呼び出しには parentToolCallId が付与されます）。/mcp を登録する拡張機能（pi-mcp-adapter）をインストールすると、組み込みサポートは無効になります。"extensions": ["-builtin:mcp"]、pi config、または実行時の --no-mcp で、意図的に無効化してください。
• 拡張機能／SDK のツールでは、エラー時に例外をスローし、エラーフラグを返さないでください。 Pi はスローされたエラーをエラーツール結果（isError: true）に変換します。正確な仕様については、ドキュメントでは packages/coding-agent/src/core/extensions/types.ts の ToolDefinition を参照しています。ツールの出力は約 50 KB／2000 行までに制限してください（DEFAULT_MAX_BYTES = 50 * 1024）。LLM に提示する列挙型には、@earendil-works/pi-ai の StringEnum を使用してください。
• スキルの name：1～64 文字で、小文字の a-z、数字の 0-9、ハイフン - のみを使用し、先頭／末尾や連続するハイフンは使用できません。description は 1024 文字以下で、読み込む「タイミング」を記述する必要があります（説明のないスキルは読み込まれません）。
• chord.md、durable.md、agent-harness.md、durable-spec.md は安定した仕様ではなく、内部実装について記述しています。 Chord はアプリケーションに依存しないもので、Pi Durable で使用されますが、Pi CLI では使用されません。 pi-durable は実験的な機能です（Pi 1.0 とともに 2026-10-01 に 1.0.0、2026-10-15 に 1.3.0）。バージョンはモノレポに追従し、それ以前のリリースには破壊的変更が含まれています。Pico5 仕様は設計文書です。保証された API ではなく、ソースツリーの状態（pi@71023aec1）を引用してください。
• Pi Durable のブログ記事は 2026-10-01 時点のスナップショットです。 「試してみる」のデモ （packages/coding-agent/src/experimental/{durable,vacation}/）は、コミット 7472cda0d により 1.2.0 で削除されました。durable ハーネス自体には影響ありません。代わりに packages/durable/test/examples/（00～31）の例を実行し、バージョンの変遷については durable.md を読んでください。
• auth.json には API キーと OAuth トークンが含まれます。Pi はファイルを 0600 で書き込みます。非公開に保ち、バージョン管理に含めないでください。認証情報の優先順位：CLI の --api-key → auth.json → 環境変数 → models.json のカスタムプロバイダー用キー。
• プロジェクト設定はエージェントディレクトリの設定より優先されます。また、リソース一覧は置き換えられるのではなく統合されます（圧縮しきい値などのモデルごとのオブジェクトは、モデルを検索する前にマージされます）。pi install -l を使うと、.pi/settings.json にパッケージ宣言を書き込めます。Pi はプロジェクトが信頼済みになった後にのみ、このファイルを読み込みます。