Pi Agent テーマカスタマイズ
Pi Agent は端末インターフェースの配色をカスタマイズできます。
この章では、組み込みテーマの使用方法とカスタムテーマの作成方法を説明します。
テーマ概要
Pi Agent はJSON形式のテーマファイルを使用して、TUIインターフェースのすべての色を定義します。
各テーマでは、次のものを定義する必要があります:必須トークン51個 + オプショントークン4個(thinkingMax、scrollbarThumb、searchMatchBg、searchMatchText)これはコアUI、メッセージ背景、Markdownレンダリング、シンタックスハイライト、エディター枠線など、さまざまなインターフェース要素の色をカバーします。
組み込みテーマ
Pi Agent には2つのテーマが組み込まれています:
| テーマ名 | 適用シーン | 説明 |
|---|---|---|
| dark | ダーク端末背景(デフォルト) | ほとんどの開発者に適したダーク端末 |
| light | ライト端末背景 | ライトテーマの端末に適しています |
初回起動時、Pi Agent は端末の背景色を自動検出し、dark または light を選択します。
対話モードで /settings と入力すると、テーマオプションで直接切り替えられます:
/settings
また、settings.json に theme フィールドを記述し、theme の値をテーマ名に変更するだけでも切り替えられます:
例
"theme": "light"
}
カスタムテーマの作成
まずテーマのディレクトリとファイルを作成します:
mkdir -p ~/.pi/agent/themes vim ~/.pi/agent/themes/my-theme.json
次にテーマファイルを定義します。以下は完全なカスタムテーマの例です:
例
"name": "my-theme",
"vars": {
"blue": "#0066cc",
"gray": 242,
"orange": "#ffaa00",
"green": "#0055AA"
},
"colors": {
"accent": "blue",
"border": "blue",
"borderAccent": "#00ffff",
"borderMuted": "gray",
"success": "green",
"error": "#ff0000",
"warning": "#ffff00",
"muted": "gray",
"dim": 240,
"text": "",
"thinkingText": "gray",
"selectedBg": "#2d2d30",
"userMessageBg": "#2d2d30",
"userMessageText": "",
"customMessageBg": "#2d2d30",
"customMessageText": "",
"customMessageLabel": "blue",
"toolPendingBg": "#1e1e2e",
"toolSuccessBg": "#1e2e1e",
"toolErrorBg": "#2e1e1e",
"toolTitle": "blue",
"toolOutput": "",
"mdHeading": "orange",
"mdLink": "blue",
"mdLinkUrl": "gray",
"mdCode": "#00ffff",
"mdCodeBlock": "",
"mdCodeBlockBorder": "gray",
"mdQuote": "gray",
"mdQuoteBorder": "gray",
"mdHr": "gray",
"mdListBullet": "#00ffff",
"toolDiffAdded": "green",
"toolDiffRemoved": "#ff0000",
"toolDiffContext": "gray",
"syntaxComment": "gray",
"syntaxKeyword": "blue",
"syntaxFunction": "#00aaff",
"syntaxVariable": "orange",
"syntaxString": "green",
"syntaxNumber": "#ff00ff",
"syntaxType": "#00aaff",
"syntaxOperator": "blue",
"syntaxPunctuation": "gray",
"thinkingOff": "gray",
"thinkingMinimal": "blue",
"thinkingLow": "#00aaff",
"thinkingMedium": "#00ffff",
"thinkingHigh": "#ff00ff",
"thinkingXhigh": "#ff0000",
"thinkingMax": "#ff0088",
"bashMode": "orange"
}
}
次に settings.json でテーマを有効にします:
例
"theme": "my-theme"
}
現在使用中のカスタムテーマファイルを編集すると、Pi Agent がテーマを自動的にホットリロードし、何もしなくても変更内容をすぐに確認できます。
テーマファイルの読み込み場所
Pi Agent は以下の場所でテーマファイルを検索します。
置く場所によって、テーマの適用範囲と読み込み条件が異なります。
| 場所 | 適用範囲 |
|---|---|
| 組み込み | dark、light は常に使用可能 |
| ~/.pi/agent/themes/*.json | グローバルテーマ。すべてのプロジェクトで使用可能 |
| .pi/themes/*.json | プロジェクトテーマ。プロジェクトを信頼した後に読み込まれる |
| Pi Packages | パッケージ内の themes/ ディレクトリ |
| --theme パス | コマンドラインによる一時読み込み |
色値の形式
Pi Agent は4つの色値形式をサポートしています:
| 形式 | 例 | 説明 |
|---|---|---|
| Hex カラー | "#ff0000" | 6桁の16進数RGBカラー |
| 256色パレット | 39 | xterm 256色パレットのインデックス(0-255) |
| 変数参照 | "blue" | vars で定義された変数を参照する |
| 端末デフォルト色 | "" | 端末のデフォルト前景色/背景色を使用する |
vars セクションは再利用可能な色変数を定義するために使用され、colors では名前で参照します。
メインカラーを変数に抽出しておくと、配色を変更する際に1か所変更するだけで済み、テーマのメンテナンスがより簡単になります。
カラートークンの分類
colors の各トークンは、インターフェース上の要素の種類ごとの色に対応しています。
以下では用途に応じてすべてのトークンを6つのカテゴリに分類し、対照しやすくしています。
コアUI(11個)
このグループは、エディターやステータスバーなどの基本インターフェース要素の色を制御します。
| トークン | 用途 |
|---|---|
| accent | メインカラー(Logo、選択項目、カーソル) |
| border | 通常の枠線 |
| borderAccent | ハイライト枠線 |
| borderMuted | エディター領域のソフトな枠線 |
| success | 成功状態 |
| error | エラー状態 |
| warning | 警告状態 |
| muted | 補助テキスト |
| dim | 第3レベルテキスト(さらに目立たない) |
| text | デフォルト文字色(通常は空にしておく) |
| thinkingText | AI推論プロセスのテキスト |
背景とコンテンツ(必須11個 + オプション3個)
このグループは、選択項目、メッセージバブル、ツール出力領域の背景と文字を制御します。
| トークン | 用途 |
|---|---|
| selectedBg | 選択項目の背景(リスト内の現在のアイテム) |
| userMessageBg | ユーザーメッセージの背景 |
| userMessageText | ユーザーメッセージのテキスト |
| customMessageBg | 拡張メッセージの背景 |
| customMessageText | 拡張メッセージのテキスト |
| customMessageLabel | 拡張メッセージのタイトルラベルの色 |
| toolPendingBg | ツール実行中の背景 |
| toolSuccessBg | ツール実行成功の背景 |
| toolErrorBg | ツール実行失敗の背景 |
| toolTitle | ツールカードのタイトルテキスト |
| toolOutput | ツール出力テキスト |
| scrollbarThumb | 全画面スクロールバーのサムの色(オプション、未指定時は selectedBg にフォールバック) |
| searchMatchBg | 検索一致の背景(オプション、未指定時は selectedBg にフォールバック) |
| searchMatchText | 検索一致のテキスト(オプション、未指定時は text にフォールバック) |
Markdown レンダリング(10個)
このグループは、AI応答内のMarkdown要素の色を制御します。
| トークン | 用途 |
|---|---|
| mdHeading | 見出し |
| mdLink | リンクテキスト |
| mdLinkUrl | リンクのURLアドレス |
| mdCode | インラインコード |
| mdCodeBlock | コードブロックの内容 |
| mdCodeBlockBorder | コードブロックの枠線 |
| mdQuote | 引用ブロックのテキスト |
| mdQuoteBorder | 引用ブロックの枠線 |
| mdHr | 区切り線 |
| mdListBullet | リストマーカー |
シンタックスハイライト(9個)
このグループは、コードブロック内のシンタックスハイライト配色を制御します。
| トークン | 用途 |
|---|---|
| syntaxComment | コメント |
| syntaxKeyword | キーワード |
| syntaxFunction | 関数名 |
| syntaxVariable | 変数名 |
| syntaxString | 文字列 |
| syntaxNumber | 数値 |
| syntaxType | 型 |
| syntaxOperator | 演算子 |
| syntaxPunctuation | 句読点 |
推論レベルの枠線(7個)
このグループは、現在の推論レベルに対応するエディター枠線のヒント色を制御します。
| トークン | 対応レベル |
|---|---|
| thinkingOff | 推論オフ |
| thinkingMinimal | 最小推論 |
| thinkingLow | 低度推論 |
| thinkingMedium | 中度推論 |
| thinkingHigh | 高度推論 |
| thinkingXhigh | 超高度推論 |
| thinkingMax | 最大推論(オプション) |
thinkingMax はオプショントークンで、定義しない場合は thinkingXhigh の色にフォールバックします。
Diff と Bash の配色(4個)
このグループは diff ハイライトと bash モードのプロンプト色を制御します。コード編集時によく目にするものです。
| トークン | 用途 |
|---|---|
| toolDiffAdded | diff の追加行(通常は緑) |
| toolDiffRemoved | diff の削除行(通常は赤) |
| toolDiffContext | diff のコンテキスト行(控えめにする) |
| bashMode | bash モードでのプロンプト色 |
HTMLエクスポートの配色
/export でセッションをHTMLにエクスポートする場合、テーマ内でエクスポートページの配色を定義できます:
例
"export": {
"pageBg": "#18181e",
"cardBg": "#1e1e24",
"infoBg": "#3c3728"
}
}
export 設定を省略すると、エクスポートページは userMessageBg から色を自動的に導出します。
テーマ作成のコツ
以下のポイントを押さえると、カスタムテーマがさまざまな端末でも安定して表示されます。
- ダーク端末:明るく彩度の高い色を使用し、コントラストを十分に高くする
- ライト端末:濃くて柔らかい色を使用し、コントラストは適度に下げてよい
- 色彩の調和:Nord、Gruvbox、Tokyo Night などの成熟した配色スキームを基礎として参考にする
- 包括的なテスト:さまざまなメッセージタイプ、ツール状態、Markdownコンテンツ、長文テキストの折り返しでも正常に表示されることを確保する