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色パレット39xterm 256色パレットのインデックス(0-255)
変数参照"blue"vars で定義された変数を参照する
端末デフォルト色""端末のデフォルト前景色/背景色を使用する

vars セクションは再利用可能な色変数を定義するために使用され、colors では名前で参照します。

メインカラーを変数に抽出しておくと、配色を変更する際に1か所変更するだけで済み、テーマのメンテナンスがより簡単になります。


カラートークンの分類

colors の各トークンは、インターフェース上の要素の種類ごとの色に対応しています。

以下では用途に応じてすべてのトークンを6つのカテゴリに分類し、対照しやすくしています。

コアUI(11個)

このグループは、エディターやステータスバーなどの基本インターフェース要素の色を制御します。

トークン用途
accentメインカラー(Logo、選択項目、カーソル)
border通常の枠線
borderAccentハイライト枠線
borderMutedエディター領域のソフトな枠線
success成功状態
errorエラー状態
warning警告状態
muted補助テキスト
dim第3レベルテキスト(さらに目立たない)
textデフォルト文字色(通常は空にしておく)
thinkingTextAI推論プロセスのテキスト

背景とコンテンツ(必須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 モードのプロンプト色を制御します。コード編集時によく目にするものです。

トークン用途
toolDiffAddeddiff の追加行(通常は緑)
toolDiffRemoveddiff の削除行(通常は赤)
toolDiffContextdiff のコンテキスト行(控えめにする)
bashModebash モードでのプロンプト色

HTMLエクスポートの配色

/export でセッションをHTMLにエクスポートする場合、テーマ内でエクスポートページの配色を定義できます:

例

{
  "export": {
    "pageBg": "#18181e",
    "cardBg": "#1e1e24",
    "infoBg": "#3c3728"
  }
}

export 設定を省略すると、エクスポートページは userMessageBg から色を自動的に導出します。


テーマ作成のコツ

以下のポイントを押さえると、カスタムテーマがさまざまな端末でも安定して表示されます。

  • ダーク端末:明るく彩度の高い色を使用し、コントラストを十分に高くする
  • ライト端末:濃くて柔らかい色を使用し、コントラストは適度に下げてよい
  • 色彩の調和:Nord、Gruvbox、Tokyo Night などの成熟した配色スキームを基礎として参考にする
  • 包括的なテスト:さまざまなメッセージタイプ、ツール状態、Markdownコンテンツ、長文テキストの折り返しでも正常に表示されることを確保する
他の拡張機能