設定

Pi は JSON 設定ファイルを使用し、プロジェクト設定がグローバル設定を上書きします。

場所	スコープ
`~/.pi/agent/settings.json`	グローバル（すべてのプロジェクト）
`.pi/settings.json`	プロジェクト（現在のディレクトリ）

直接編集するか、/settings で一般的なオプションを設定できます。

プロジェクト信頼

対話起動時、プロジェクトローカルの設定、リソース、またはプロジェクト .agents/skills を含むプロジェクトフォルダがあり、~/.pi/agent/trust.json にそのフォルダまたは親フォルダの保存済み決定がない場合、pi は信頼する前に確認します。プロジェクトを信頼すると、pi は .pi/settings.json と .pi リソースの読み込み、不足プロジェクトパッケージのインストール、プロジェクト拡張の実行が可能になります。

非対話モード（-p、--mode json、--mode rpc）では信頼プロンプトは表示されません。適用可能な保存済み信頼決定がない場合、グローバル設定の defaultProjectTrust を使用します：ask（デフォルト）と never はそれらのプロジェクトリソースを無視し、always は信頼します。--approve/-a または --no-approve/-na で 1 回の実行のプロジェクト信頼を上書きできます。

拡張または保存済み決定が適用されない場合、defaultProjectTrust がフォールバック動作を制御します。~/.pi/agent/settings.json で "ask"、"always"、"never" に設定するか、/settings で変更してください。

pi config とパッケージコマンドは同じプロジェクト信頼フローを使用しますが、pi update はプロンプトしません。--approve で 1 コマンド分プロジェクトローカル設定を信頼するか、--no-approve で無視します。

対話モードで /trust を使用して、将来のセッション用にプロジェクト信頼決定を保存できます。直接の親フォルダの信頼も含みます。~/.pi/agent/trust.json にのみ書き込みます。現在のセッションは再読み込みされないため、変更を反映するには pi を再起動してください。

すべての設定

モデルと思考

設定	型	デフォルト	説明
`defaultProvider`	string	-	デフォルトプロバイダー（例：`"anthropic"`、`"openai"`）
`defaultModel`	string	-	デフォルトモデル ID
`defaultThinkingLevel`	string	-	`"off"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`
`hideThinkingBlock`	boolean	`false`	出力で思考ブロックを非表示
`thinkingBudgets`	object	-	思考レベルごとのカスタムトークン予算

thinkingBudgets

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

UI と表示

設定	型	デフォルト	説明
`theme`	string	`"dark"`	テーマ名（`"dark"`、`"light"`、またはカスタム）
`quietStartup`	boolean	`false`	起動ヘッダーを非表示
`defaultProjectTrust`	string	`"ask"`	フォールバックのプロジェクト信頼動作：`"ask"`、`"always"`、`"never"`。グローバル設定のみ
`collapseChangelog`	boolean	`false`	更新後に要約された変更ログを表示
`enableInstallTelemetry`	boolean	`true`	初回インストールまたは変更ログ検出更新後に匿名のインストール/更新バージョンピングを送信。更新チェックは制御しない
`enableAnalytics`	boolean	`false`	オプトインの分析データ共有。現在は実験的初回セットアップ（`PI_EXPERIMENTAL=1`）時のみ確認
`trackingId`	string	-	分析トラッキング識別子。`enableAnalytics` 有効化時に生成
`doubleEscapeAction`	string	`"tree"`	ダブル Esc のアクション：`"tree"`、`"fork"`、`"none"`
`treeFilterMode`	string	`"default"`	`/tree` のデフォルトフィルター：`"default"`、`"no-tools"`、`"user-only"`、`"labeled-only"`、`"all"`
`editorPaddingX`	number	`0`	入力エディターの水平パディング（0-3）
`autocompleteMaxVisible`	number	`5`	オートコンプリートドロップダウンの最大表示件数（3-20）
`showHardwareCursor`	boolean	`false`	TUI が IME サポートのためにカーソルを配置する際にターミナルカーソルを表示

テレメトリと更新チェック

enableInstallTelemetry は https://pi.dev/api/report-install への匿名インストール/更新ピングのみを制御します。テレメトリをオプトアウトしても更新チェックは無効になりません。Pi は引き続き https://pi.dev/api/latest-version を取得して最新バージョンを確認できます。

PI_SKIP_VERSION_CHECK=1 を設定すると Pi バージョン更新チェックを無効化できます。--offline または PI_OFFLINE=1 で、ここで説明するすべての起動時ネットワーク操作（更新チェック、パッケージ更新チェック、インストール/更新テレメトリを含む）を無効化できます。

ネットワーク

設定	型	デフォルト	説明
`httpProxy`	string	-	`HTTP_PROXY` と `HTTPS_PROXY` として適用される HTTP プロキシ URL。グローバル設定のみ。

{
  "httpProxy": "http://127.0.0.1:7890"
}

警告

設定	型	デフォルト	説明
`warnings.anthropicExtraUsage`	boolean	`true`	Anthropic サブスクリプション認証が有料の追加使用量を使う可能性がある場合に警告を表示

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

コンパクション

設定	型	デフォルト	説明
`compaction.enabled`	boolean	`true`	自動コンパクションを有効化
`compaction.reserveTokens`	number	`16384`	LLM 応答用に予約するトークン
`compaction.keepRecentTokens`	number	`20000`	保持する最近のトークン（要約しない）

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

ブランチ要約

設定	型	デフォルト	説明
`branchSummary.reserveTokens`	number	`16384`	ブランチ要約用に予約するトークン
`branchSummary.skipPrompt`	boolean	`false`	`/tree` ナビゲーション時の「Summarize branch?」プロンプトをスキップ（デフォルトは要約なし）

リトライ

設定	型	デフォルト	説明
`retry.enabled`	boolean	`true`	一時的エラー時のエージェントレベル自動リトライを有効化
`retry.maxRetries`	number	`3`	エージェントレベルの最大リトライ回数
`retry.baseDelayMs`	number	`2000`	エージェントレベル指数バックオフの基本遅延（2s、4s、8s）
`retry.provider.timeoutMs`	number	SDK default	プロバイダー/SDK リクエストタイムアウト（ミリ秒）
`retry.provider.maxRetries`	number	`0`	プロバイダー/SDK リトライ回数
`retry.provider.maxRetryDelayMs`	number	`60000`	失敗前のサーバー要求最大遅延（60s）

プロバイダーが retry.provider.maxRetryDelayMs より長いリトライ遅延を要求した場合（例：Google の「quota will reset after 5h」）、リクエストは黙って待つのではなく、情報を含むエラーですぐに失敗します。0 に設定すると上限を無効化できます。

プロバイダーレベルのリトライが明示的に必要でない限り、retry.provider.maxRetries は 0 のままにしてください。0 より大きく設定すると、SDK/プロバイダーのリトライが Pi が検知する前に使用量上限超過エラーを処理し、状況によってはプロバイダークォータがリセットされるまでエージェントがブロックされる可能性があります。

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

メッセージ配信

設定	型	デフォルト	説明
`steeringMode`	string	`"one-at-a-time"`	ステアリングメッセージの送信方法：`"all"` または `"one-at-a-time"`
`followUpMode`	string	`"one-at-a-time"`	フォローアップメッセージの送信方法：`"all"` または `"one-at-a-time"`
`transport`	string	`"auto"`	複数トランスポートをサポートするプロバイダーの優先トランスポート：`"sse"`、`"websocket"`、`"websocket-cached"`、`"auto"`
`httpIdleTimeoutMs`	number	`300000`	HTTP ヘッダー/ボディのアイドルタイムアウト（ミリ秒）。明示的なストリームアイドルタイムアウトを持つプロバイダーでも使用。`0` で無効化。
`websocketConnectTimeoutMs`	number	`15000`	WebSocket トランスポートをサポートするプロバイダーの WebSocket 接続/オープンハンドシェイクタイムアウト（ミリ秒）。`0` で無効化。

ターミナルと画像

設定	型	デフォルト	説明
`terminal.showImages`	boolean	`true`	ターミナルに画像を表示（サポートされている場合）
`terminal.imageWidthCells`	number	`60`	ターミナルセルでのインライン画像の推奨幅
`terminal.clearOnShrink`	boolean	`false`	コンテンツ縮小時に空行をクリア（ちらつきの原因になる場合あり）
`images.autoResize`	boolean	`true`	画像を最大 2000x2000 にリサイズ
`images.blockImages`	boolean	`false`	LLM への画像送信をすべてブロック

Shell

設定	型	デフォルト	説明
`shellPath`	string	-	カスタム shell パス（例：Windows の Cygwin）
`shellCommandPrefix`	string	-	すべての bash コマンドのプレフィックス（例：`"shopt -s expand_aliases"`）
`npmCommand`	string[]	-	npm パッケージ検索/インストール操作用のコマンド argv（例：`["mise", "exec", "node@20", "--", "npm"]`）

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand はインストール、アンインストール、git パッケージ内の依存関係インストールを含むすべての npm パッケージマネージャー操作に使用されます。ユーザースコープの npm パッケージは ~/.pi/agent/npm/ に、プロジェクトスコープの npm パッケージは .pi/npm/ にインストールされます。プロセス起動方法どおりに argv 形式のエントリを使用してください。npmCommand が設定されている場合、git パッケージの依存関係インストールはラッパーや代替パッケージマネージャーの npm 固有フラグを避けるため plain install を使用します。

セッション

設定	型	デフォルト	説明
`sessionDir`	string	-	セッションファイルを保存するディレクトリ。絶対パス、相対パス、`~` を受け付けます。

{ "sessionDir": ".pi/sessions" }

複数のソースがセッションディレクトリを指定する場合、優先順位は --session-dir、PI_CODING_AGENT_SESSION_DIR、settings.json の sessionDir です。

モデルサイクル

設定	型	デフォルト	説明
`enabledModels`	string[]	-	Ctrl+P サイクル用のモデルパターン（`--models` CLI フラグと同じ形式）

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown

設定	型	デフォルト	説明
`markdown.codeBlockIndent`	string	`" "`	コードブロックのインデント

リソース

これらの設定は、拡張、スキル、プロンプト、テーマをどこから読み込むかを定義します。

~/.pi/agent/settings.json のパスは ~/.pi/agent 基準で解決されます。.pi/settings.json のパスは .pi 基準で解決されます。絶対パスと ~ がサポートされています。

設定	型	デフォルト	説明
`packages`	array	`[]`	リソースを読み込む npm/git パッケージ
`extensions`	string[]	`[]`	ローカル拡張ファイルパスまたはディレクトリ
`skills`	string[]	`[]`	ローカルスキルファイルパスまたはディレクトリ
`prompts`	string[]	`[]`	ローカルプロンプトテンプレートパスまたはディレクトリ
`themes`	string[]	`[]`	ローカルテーマファイルパスまたはディレクトリ
`enableSkillCommands`	boolean	`true`	スキルを `/skill:name` コマンドとして登録

配列は glob パターンと除外をサポートします。!pattern で除外。+path で正確なパスを強制包含、-path で強制除外。

packages

文字列形式はパッケージからすべてのリソースを読み込みます：

{
  "packages": ["pi-skills", "@org/my-extension"]
}

オブジェクト形式は読み込むリソースをフィルタリングします：

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

パッケージ管理の詳細は packages.md を参照してください。

例

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

プロジェクト上書き

プロジェクト設定（.pi/settings.json）はグローバル設定を上書きします。ネストされたオブジェクトはマージされます：

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}