oracle

Oracle（CLI）— 最適な使い方

Oracle は、プロンプトと選択したファイルをまとめて 1 回限りのリクエストにし、別のモデルが実際のリポジトリのコンテキストを踏まえて回答できるようにします（API またはブラウザー自動化）。出力は参考情報として扱い、コードベースとテストで検証してください。

主なユースケース（ブラウザー、GPT‑5.5 Pro）

ここでのデフォルトのワークフローは、ChatGPT で GPT‑5.5 Pro を使う --engine browser です。これは「人間が介在する」方法で、所要時間は約 10 分から約 1 時間です。保存されたセッションに再接続できることを想定してください。

推奨されるデフォルト設定：

• エンジン：browser（--engine browser）
• モデル：GPT‑5.5 Pro（--model gpt-5.5-pro または ChatGPT のピッカーラベル（例：--model "5.5 Pro"））
• 添付ファイル：ディレクトリ／glob と除外指定を使用し、シークレットは避けてください。

推奨手順（高速かつ安定）

1. 必要な情報を含む、できるだけ少数のファイルを選びます。
2. 送信する内容をプレビューします（必要に応じて --dry-run と --files-report を使用します）。
3. 通常の GPT‑5.5 Pro の ChatGPT ワークフローではブラウザーモードで実行します。API は明示的に使いたい場合にのみ使用します。
4. 実行が切断されたりタイムアウトしたりした場合は、保存されたセッションに再接続します（再実行しないでください）。

コマンド（推奨）

• ヘルプを表示します（セッションごとに 1 回）：

  • npx -y @steipete/oracle --help

• プレビューします（トークンを消費しません）：

  • npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
  • npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"

• トークン数／コストを確認します：

  • npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"

• 起動／パフォーマンスのトレース：

  • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"
  • CLI の起動や最初の出力までの時間が遅いと感じる場合に使用し、first-output と exit を確認します。

• ブラウザーで実行します（主な方法。長時間の実行は通常どおりです）：

  • npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"

• 手動で貼り付ける場合の代替手順（バンドルを作成してクリップボードにコピーします）：

  • npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"
  • 注：--copy は --copy-markdown の非表示のエイリアスです。

ファイルの添付（--file）

--file はファイル、ディレクトリ、glob を受け付けます。複数回指定でき、エントリーはカンマ区切りにもできます。

• 含める場合：

  • --file "src/**"（ディレクトリの glob）
  • --file src/index.ts（ファイルを直接指定）
  • --file docs --file README.md（ディレクトリとファイルを直接指定）

• 除外する場合（先頭に ! を付けます）：

  • --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

• デフォルト設定（実装に基づく重要な動作）：

  • デフォルトで無視されるディレクトリ：node_modules、dist、coverage、.git、.turbo、.next、build、tmp（リテラルのディレクトリ／ファイルとして明示的に渡さない限りスキップされます）。
  • glob の展開時に .gitignore を尊重します。
  • シンボリックリンクはたどりません（glob の展開では followSymbolicLinks: false を使用します）。
  • ドットファイルは、ドットで始まるパス要素を含むパターン（例：--file ".github/**"）で明示的に指定しない限り、除外されます。
  • デフォルトの上限：1 MB を超えるファイルは、ORACLE_MAX_FILE_SIZE_BYTES または ~/.oracle/config.json の maxFileSizeBytes を引き上げない限り拒否されます。

使用量と可観測性

• 目標：入力全体を約 196k トークン未満に抑えます。
• 支出の前にトークンを多く消費するファイルを特定するには、--files-report（および／または --dry-run json）を使用します。
• 起動時間と最初の出力までの時間を計測するには、--perf-trace／ORACLE_PERF_TRACE=1 を使用します。トレースではプロンプト、トークン、キー、Cookie、インラインの Cookie ペイロードがマスキングされます。切り離された API 子プロセスは、セッション名を付けたサイドカートレースを書き込みます。
• 非表示の設定や高度な設定が必要な場合：npx -y @steipete/oracle --help --verbose。

エンジン（API 対ブラウザー）

• 自動選択：OPENAI_API_KEY が設定されている場合は api を、それ以外の場合は browser を使用します。
• ブラウザーエンジンがサポートするのは GPT と Gemini のみです。Claude、Grok、Codex、または複数モデルで実行する場合は --engine api を使用してください。
• API の実行には使用料金が発生するため、開始前にユーザーの明示的な同意が必要です。
• ブラウザーの添付ファイル：
  • --browser-attachments auto|never|always（auto は約 60k 文字まではインラインで貼り付け、それを超えるとアップロードします）。
  • 多数のテキストファイルをファイル名を保持したまま 1 つの ZIP としてアップロードするには、--browser-bundle-files --browser-bundle-format zip を追加します。
• リモートブラウザーホスト（サインイン済みのマシンで自動化を実行します）：
  • ホスト：oracle serve --host 0.0.0.0 --port 9473 --token <secret>
  • クライアント：oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"

API の事前確認

• API の実行にはユーザーの明示的な同意が必要で、料金が発生します。
• API を実行する前に、秘密情報を表示せずにプロバイダーの準備状況を確認してください：
  • oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
  • oracle --preflight --models gpt-5.4,gemini-3-pro
  • oracle --route --model gpt-5.4
• OpenAI のファーストパーティサービスを使用する場合は、--provider openai または --no-azure を渡してください。これにより、エクスポート済みの Azure 環境変数や設定によってルートが乗っ取られるのを防げます：
  • oracle --provider openai --engine api --model gpt-5.5-pro ...
• 部分的な成功にも価値がある、助言を目的とした複数モデルのパネルでは、--allow-partial --write-output <path> を使用してください。成功したモデルのファイルと <stem>.oracle.json マニフェストを簡単に取得できます：
  • oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<task>"
• --timeout 10m は通常のユーザー向け API の期限です。--http-timeout が明示的に設定されていない場合、Oracle はこれを基に HTTP トランスポートのタイムアウトを設定します。
• エクスポート済みの OPENAI_API_KEY が無効で、ユーザーが個人用の OpenAI キーを使いたい場合は、1 つの永続的な tmux セッションで $one-password を使用してください。既知の項目：API Key - OpenAI - Personal、フィールド：api_key。キーは単一の Oracle コマンドにのみ注入し、決して表示しないでください：
  • OPENAI_API_KEY="$(op item get 'API Key - OpenAI - Personal' --account my.1password.com --fields label=api_key --reveal)" oracle --provider openai --engine api --model gpt-5.5-pro ...
• Oracle 自体をデバッグする場合は、~/Projects/oracle をプルした後、ローカルのチェックアウトを使用することをおすすめします：
  • pnpm -C ~/Projects/oracle run build
  • node ~/Projects/oracle/dist/scripts/run-cli.js ...

セッションとスラッグ（作業を失わないために）

• ~/.oracle/sessions に保存されます（ORACLE_HOME_DIR で上書きできます）。
• ブラウザーでの実行では、transcript.md、Deep Research のレポート、利用可能な場合は ChatGPT が生成してダウンロードした画像などの永続ファイルが、~/.oracle/sessions/<id>/artifacts/ に保存されます。
• 実行はデタッチされたり、長時間かかったりすることがあります（特にブラウザー/API と GPT‑5.5 Pro の組み合わせ）。CLI がタイムアウトした場合は、再実行せずに再接続してください。
  • 一覧表示：oracle status --hours 72
  • 接続：oracle session <id> --render
• セッション ID を読みやすくするには、--slug "<3-5 words>" を使用してください。
• プロンプトの重複を防ぐ機能があります。本当に新しく実行したい場合にのみ --force を使用してください。
• CLI のガードレール：プロンプトなしで root 実行すると、ゼロ以外の終了コードで終了します。--dry-run は --render／--render-markdown と併用できません。Ctrl-C はフォアグラウンドの API 実行をコード 130 で終了させますが、ブラウザーのクリーンアップ／再接続は引き続き実行されます。

プロンプトのテンプレート（高シグナル）

Oracle はプロジェクトに関する知識がまったくない状態で開始します。モデルが技術スタック、ビルドツール、規約、または「明白な」パスを推測できるとは考えないでください。以下を含めてください：

• プロジェクトの概要（技術スタック＋ビルド／テストコマンド＋プラットフォームの制約）。
• 「ファイルの配置」（主要なディレクトリ、エントリーポイント、設定ファイル、依存関係の境界）。
• 正確な質問＋試したこと＋エラーテキスト（原文のまま）。
• 制約（「X は変更しない」、「公開 API を維持する」、「パフォーマンス予算」など）。
• 希望する出力（「パッチの計画＋テストを返す」、「リスクのある仮定を列挙する」、「トレードオフを示して 3 つの選択肢を提示する」）。

「網羅的なプロンプト」パターン（後で再現するため）

長時間の調査になると分かっている場合は、後から単独で使えるプロンプトを作成します。

• 冒頭：プロジェクトの概要と現在の目標を、6～30文で記述します。
• 中段：具体的な再現手順、正確なエラー、すでに試したことを記載します。
• 末尾：新しいモデルが状況を完全に理解するために必要なコンテキストファイルをすべて添付します（エントリーポイント、設定ファイル、主要モジュール、ドキュメント）。

後で同じコンテキストを再現する必要がある場合は、同じプロンプトと --file … の設定で再実行します（Oracle の実行は一度きりで、モデルは以前の実行を記憶しません）。

安全性

• 既定では秘密情報（.env、キーのファイル、認証トークン）を添付しないでください。十分に伏せ字にし、必要なものだけを共有してください。
• 「必要十分なコンテキスト」を優先してください。プロンプトを改善してファイル数を減らすほうが、リポジトリ全体を大量にダンプするより効果的です。