Pi Agent 設定リファレンスマニュアル
以下は Pi Agent settings.json 設定項目の早見表です。
この表には一般的な設定項目がまとめられており、一部の JSON 専用の上級キー（tuiMode、fullscreen シリーズ、terminal.hyperlinks、markdown.mermaid など）は個別には記載されていません。
設定ファイルの場所
設定はグローバルとプロジェクトの2つの階層に分かれており、プロジェクト設定はプロジェクトの信頼を取得した後にのみ読み込まれます。
| ファイルパス | 適用範囲 | 説明 |
|---|---|---|
| ~/.pi/agent/settings.json | グローバル（全プロジェクト） | すべてのプロジェクトに適用される共通設定 |
| .pi/settings.json | プロジェクトレベル | プロジェクトが信頼された場合にのみ読み込まれ、グローバル設定の同名キーを上書きします。 |
モデルと推論
このセクションの設定は、デフォルトで使用するプロバイダー、モデル、推論の強度を決定します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| defaultProvider | string | 任意 | なし（初回は /login または /model で設定） | デフォルトのプロバイダー（例: "anthropic"、"openai"） |
| defaultModel | string | 任意 | なし（初回は /login または /model で設定） | デフォルトのモデル ID（例: "claude-sonnet-4-20250514"） |
| defaultThinkingLevel | string | 任意 | なし（ドキュメントに記載なし） | デフォルトの推論レベル：off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | object | 任意 | 无 | "provider/modelId" 単位で各モデルの起動時推論レベルを設定 |
| hideThinkingBlock | boolean | 任意 | false | 推論プロセスを非表示にする |
| showCacheMissNotices | boolean | 任意 | false | キャッシュミス通知を表示する |
| thinkingBudgets | object | 任意 | なし（カスタム予算は無効） | 各レベルのトークン予算をカスタマイズ |
| warnings.anthropicExtraUsage | boolean | 任意 | true | Anthropic サブスクリプションで有料の追加使用量が発生する可能性がある場合に通知 |
UIと表示
このセクションの設定は、インターフェースの外観、外部エディター、表示密度を制御します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| theme | string | 任意 | "dark" | テーマ名 |
| externalEditor | string | 任意 | 順に $VISUAL、$EDITOR を使用し、どちらもない場合は Windows では Notepad、その他のシステムでは nano を使用 | 外部エディターコマンド（明示的な設定は環境変数より優先） |
| quietStartup | boolean | 任意 | false | 起動時ヘッダーを非表示にする |
| defaultProjectTrust | string | 任意 | "ask" | プロジェクト信頼のデフォルト動作："ask"（確認）、"always"（自動信頼）、"never"（自動拒否）。グローバル設定のみ有効 |
| collapseChangelog | boolean | 任意 | false | 更新ログを折りたたむ |
| enableInstallTelemetry | boolean | 任意 | true | 匿名インストール統計 |
| enableAnalytics | boolean | 任意 | false | ユーザー行動分析（明示的に有効化する必要あり） |
| doubleEscapeAction | string | 任意 | "tree" | Escape をダブルクリックしたときに実行されるアクション。デフォルトではセッションツリーブラウザを開く |
| treeFilterMode | string | 任意 | "default" | /tree のデフォルトフィルターモード：default/no-tools/user-only/labeled-only/all |
| editorPaddingX | number | 任意 | 0 | エディターの水平パディング（0〜3） |
| outputPad | number | 任意 | 1 | メッセージのパディング（0 または 1） |
| autocompleteMaxVisible | number | 任意 | 5 | 自動補完の最大項目数（3〜20） |
ネットワーク
このセクションの設定は、制限されたネットワーク環境でのプロキシ接続に使用されます。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| httpProxy | string | 任意 | なし（プロキシを使用しない） | HTTP プロキシ（グローバルのみ） |
httpProxyグローバル設定でのみ有効で、プロジェクトレベルの設定に記述しても無効です。
プロキシが必要な場合は記述してください~/.pi/agent/settings.json。
圧縮
このセクションの設定は、コンテキスト自動圧縮のトリガーと保持ポリシーを制御します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| compaction.enabled | boolean | 任意 | true | 自動圧縮 |
| compaction.reserveTokens | number | 任意 | 16384 | LLM 応答用に予約するトークン |
| compaction.keepRecentTokens | number | 任意 | 20000 | 保持する最近のトークン |
ブランチ要約
このセクションの設定は、セッションツリー間を移動する際に破棄されたブランチの要約を生成するかどうかを制御します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| branchSummary.reserveTokens | number | 任意 | 16384 | 要約用に予約するトークン |
| branchSummary.skipPrompt | boolean | 任意 | false | 要約プロンプトをスキップする |
リトライ
このセクションの設定は、リクエスト失敗後の自動リトライ動作を制御します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| retry.enabled | boolean | 任意 | true | 自動リトライ |
| retry.maxRetries | number | 任意 | 3 | 最大リトライ回数 |
| retry.baseDelayMs | number | 任意 | 2000 | 基本遅延（ms） |
| retry.provider.timeoutMs | number | 任意 | SDK デフォルト | リクエストタイムアウト |
| retry.provider.maxRetries | number | 任意 | 0 | プロバイダー別のリトライ回数 |
| retry.provider.maxRetryDelayMs | number | 任意 | 60000 | 最大リトライ遅延 |
メッセージ配信
このセクションの設定は、ガイドメッセージとフォローアップメッセージの挿入方法、および使用する転送プロトコルを決定します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| steeringMode | string | 任意 | "one-at-a-time" | ガイドメッセージのポリシー："all"（すべてのガイドメッセージを即座に挿入）または "one-at-a-time"（1件ずつ挿入） |
| followUpMode | string | 任意 | "one-at-a-time" | フォローアップメッセージのポリシー |
| transport | string | 任意 | "auto" | 転送プロトコル：sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | number | 任意 | 300000 | HTTP アイドルタイムアウト |
| websocketConnectTimeoutMs | number | 任意 | 15000 | WebSocket 接続タイムアウト |
ターミナルと画像
このセクションの設定は、ターミナル内での画像の表示サイズと送信動作を制御します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| terminal.showImages | boolean | 任意 | true | ターミナルでの画像表示 |
| terminal.imageWidthCells | number | 任意 | 60 | 画像の幅（セル） |
| terminal.clearOnShrink | boolean | 任意 | false | コンテンツ縮小時に空行をクリアする |
| images.autoResize | boolean | 任意 | true | 画像の自動スケーリング |
| images.blockImages | boolean | 任意 | false | LLM への画像送信をブロックする |
Shell
このセクションの設定は、コマンド実行時に使用するシェルと npm ラッパーをカスタマイズするためのものです。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| shellPath | string | 任意 | なし（システムデフォルトのシェルを使用） | カスタムシェルパス |
| shellCommandPrefix | string | 任意 | なし（プレフィックスなし） | コマンドプレフィックス |
| npmCommand | string[] | 任意 | なし（npm を直接呼び出し） | npm コマンドラッパー |
組み込みツール
このセクションの設定は、起動時にデフォルトで有効になる組み込みツールのセットを制御します。
| 設定項目 | 型 | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| defaultTools | string[] | 任意 | なし（組み込みのデフォルトツールセットを使用） | 初期に有効化される組み込みツール。選択可能な値は read/bash/powershell/edit/write/grep/find/ls。powershell は Windows のみ提供されます。 |
この設定は組み込みツールのみに影響します。拡張機能や SDK で登録されたカスタムツールには影響しません。
プロジェクトレベルの defaultTools 配列は、グローバル配列を全体として置き換えます。
モデルループとリソース
このセクションでは、Ctrl+P のモデルループ範囲、および拡張機能、Skill などのリソースの読み込みパスを設定します。
| 設定項目 | タイプ | 必須かどうか | デフォルト値 | 説明 |
|---|---|---|---|---|
| enabledModels | string[] | 任意 | なし（利用可能なすべてのモデル） | Ctrl+P で使用可能なモデル |
| packages | array（文字列またはオブジェクトの混合） | 任意 | [] | パッケージのソース。文字列形式ではすべてのリソースを読み込み、オブジェクト形式では {source, skills, extensions} などのフィールドでフィルタリングします。 |
| extensions | string[] | 任意 | [] | 拡張機能のパス |
| skills | string[] | 任意 | [] | Skill のパス |
| prompts | string[] | 任意 | [] | テンプレートのパス |
| themes | string[] | 任意 | [] | テーマのパス |
| enableSkillCommands | boolean | 任意 | true | /skill:name コマンドを登録 |
| sessionDir | string | 任意 | なし（~/.pi/agent/sessions/ を使用） | セッション保存ディレクトリ |