pi-customization

Pi のカスタマイズ

根拠

1. pi-mono/packages/coding-agent/docs/themes.md — テーマ JSON の形式（name、任意の vars、必須の 51 個の colors トークン）、配置場所（~/.pi/agent/themes/*.json、.pi/themes/*.json、パッケージ、設定、CLI の --theme）、ホットリロード、色の値の形式。
2. pi-mono/packages/coding-agent/docs/keybindings.md — ~/.pi/agent/keybindings.json を使ったカスタマイズ、名前空間付きアクション ID（tui.input.submit、tui.editor.cursorUp、app.interrupt など）、キーの形式（modifier+key）、すべてのアクションの一覧表。
3. pi-mono/packages/coding-agent/docs/prompt-templates.md — /name で呼び出す Markdown スニペット、配置場所（~/.pi/agent/prompts/*.md、.pi/prompts/*.md、パッケージ）、位置引数（$1、$2、$@、${@:N}）、任意の description を指定できる YAML フロントマター。
4. pi-mono/packages/coding-agent/README.md — .pi/SYSTEM.md、~/.pi/agent/SYSTEM.md、APPEND_SYSTEM.md に関するコンテキストファイルのセクション。
5. pi-mono/packages/coding-agent/docs/settings.md — これらを連携させるための settings.json 全体の構造。

不変条件

• テーマの形式：テーマでは、必須かつ一意の name、再利用可能な色のエイリアスを指定する任意の vars、および 51 個すべての colors トークンを定義します。トップレベルキーに type、ui、syntax、borders はありません。すべて colors の下にあります。~/.pi/agent/themes/*.json（グローバル）および .pi/themes/*.json（プロジェクト）から読み込まれます。
• キーバインドの設定：キーバインドは settings.json ではなく、~/.pi/agent/keybindings.json で設定します。ID には名前空間が付いています（tui.input.submit（送信）、tui.editor.cursorUp、app.interrupt など）。再起動せずに変更を適用するには、/reload を実行します。
• プロンプトテンプレートの引数：テンプレートでは $1、$2、$@、${@:N} の位置引数構文を使います。{variable} や <include> ではありません。ファイル名（.md を除く）が /name コマンドになります。
• システムプロンプトの上書き：デフォルトのシステムプロンプトを置き換えるには、.pi/SYSTEM.md（プロジェクト）または ~/.pi/agent/SYSTEM.md（グローバル）を使います。置き換えずに追加するには、APPEND_SYSTEM.md を使います。上書き後も、コンテキストファイルとスキルはその後に追加されます。

ワークフロー

• テーマを作成する：packages/coding-agent/src/modes/interactive/theme/ の dark.json をコピーし、colors キーの下にある色の値をカスタマイズして、~/.pi/agent/themes/ に配置します。/settings または pi --theme <name> で選択します。
• キーを上書きする：アクション ID をキー配列に対応付けた ~/.pi/agent/keybindings.json を作成または編集します（例："tui.input.submit": ["ctrl+enter"]）。適用するには /reload を実行します。
• プロンプトテンプレートを作成する：任意の YAML フロントマター（description）を付けた .md ファイルを ~/.pi/agent/prompts/ に作成します。引数には $1、$@ を使います。エディターで /filename を実行して呼び出します。
• システムプロンプトを上書きする：デフォルトのシステムプロンプトを置き換えるには、プロジェクトに .pi/SYSTEM.md、またはグローバルに ~/.pi/agent/SYSTEM.md を作成します。カスタム指示を追加する場合は、同じ場所に APPEND_SYSTEM.md を作成します。

アンチパターン

• エージェントのコンポーネントのソースコードにキーバインドをハードコードしないでください。keybindings.md に記載された設定可能な名前空間を使います。
• キーバインドを settings.json に記述しないでください。キーバインド専用のファイル（~/.pi/agent/keybindings.json）を使います。
• プロンプトテンプレートで {variable} や <include src="..."> 構文を使わないでください。実際に使う構文は $1、$@、${@:N} です。