Oracle (CLI) — 最善の使い方
Oracleは、プロンプトと選択したファイルを「ワンショット」リクエストにバンドルし、別のモデルが実際のリポジトリコンテキストを使って回答できるようにします(APIまたはブラウザ自動化)。出力は参考として扱い、コードベースとテストで検証してください。
主なユースケース(ブラウザ、GPT‑5.5 Pro)
ここでのデフォルトワークフローは、ChatGPT上のGPT‑5.5 Proを--engine browserで使用します。これは「人間が介在する」パスで、約10分〜1時間かかることがあります。保存されたセッションに後から再アタッチできることを想定しています。
推奨デフォルト:
- エンジン:ブラウザ(
--engine browser) - モデル:GPT‑5.5 Pro(
--model gpt-5.5-proまたはChatGPTのピッカーラベル--model "5.5 Pro"のいずれか) - 添付ファイル:ディレクトリ/glob + 除外指定。機密情報は避ける。
黄金のパス(高速かつ信頼性)
- 厳選したファイルセットを選ぶ(真実を含む最小限のファイル)。
- 送信内容をプレビューする(必要に応じて
--dry-run+--files-report)。 - 通常のGPT‑5.5 Pro ChatGPTワークフローにはブラウザモードで実行。APIは明示的に必要な場合のみ使用。
- 実行がデタッチ/タイムアウトした場合:保存されたセッションに再アタッチする(再実行しない)。
コマンド(推奨)
-
ヘルプを表示(セッションあたり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を起動時間と最初の出力時間の計測に使用。トレースはプロンプト、トークン、キー、クッキー、インラインのクッキーペイロードを編集します。デタッチされたAPI子プロセスは、セッションサフィックス付きのサイドカートレースを書き込みます。- 隠された高度な設定が必要な場合:
npx -y @steipete/oracle --help --verbose
エンジン(API vs ブラウザ)
- 自動選択:
OPENAI_API_KEYが設定されている場合はapiを、そうでない場合はbrowserを使用します。 - ブラウザエンジンはGPT + Geminiのみをサポート。Claude/Grok/Codexやマルチモデル実行には
--engine apiを使用します。 - API実行は、使用コストが発生するため、開始前に明示的なユーザー同意が必要です。
- ブラウザの添付ファイルオプション:
--browser-attachments auto|never|always(自動では約60k文字までインラインペーストし、それ以上はアップロードします)。--browser-bundle-files --browser-bundle-format zipを追加すると、多数のテキストファイルを1つの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-prooracle --preflight --models gpt-5.4,gemini-3-prooracle --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期限です。Oracleは、--http-timeoutが明示的に設定されていない限り、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 buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
セッションとスラッグ(作業を失わないために)
~/.oracle/sessionsに保存されます(ORACLE_HOME_DIRで上書き可能)。- ブラウザ実行は、
~/.oracle/sessions/<id>/artifacts/以下に持続的なファイルを保存します。これにはtranscript.md、Deep Researchレポート、ダウンロード可能なChatGPT生成画像などが含まれます。 - 実行はデタッチしたり、長時間かかる場合があります(ブラウザ/API + GPT‑5.5 Proはしばしばそうなります)。CLIがタイムアウトした場合:再実行せず、再アタッチしてください。
- 一覧表示:
oracle status --hours 72 - アタッチ:
oracle session <id> --render
- 一覧表示:
--slug "<3-5単語>"を使用して、セッションIDを読みやすくします。- 重複プロンプトガードが存在します。本当に新しい実行が必要な場合にのみ
--forceを使用してください。 - CLIガードレール:プロンプトなしでのroot実行はゼロ以外で終了します。
--dry-runは--render/--render-markdownと競合します。Ctrl-Cは、ブラウザのクリーンアップ/再アタッチがまだ実行中の場合、フォアグラウンドのAPI実行をコード130で終了します。
プロンプトテンプレート(高信号)
Oracleはゼロのプロジェクト知識から始まります。モデルがスタック、ビルドツール、規約、「明白な」パスを推測できないことを前提としてください。以下を含めてください:
- プロジェクト概要(スタック + ビルド/テストコマンド + プラットフォームの制約)。
- 「どこに何があるか」(主要ディレクトリ、エントリポイント、設定ファイル、依存関係の境界)。
- 正確な質問 + 試したこと + エラーテキスト(そのまま)。
- 制約(「Xを変更しない」「公開APIを維持する」「パフォーマンス予算」など)。
- 期待する出力(「パッチ計画とテストを返す」「リスクのある前提を列挙する」「トレードオフを含む3つのオプションを示す」)。
「網羅的プロンプト」パターン(後で復元するため)
これが長い調査になると分かっている場合、後で単独で機能するプロンプトを書いてください:
- 冒頭:6~30文のプロジェクト概要 + 現在の目標。
- 中盤:具体的な再現手順 + 正確なエラー + 既に試したこと。
- 末尾:新しいモデルが完全に理解できるように、すべてのコンテキストファイルを添付(エントリポイント、設定、主要モジュール、ドキュメント)。
同じコンテキストを後で再現する必要がある場合、同じプロンプト + --file … セットで再実行してください(Oracleの実行はワンショットです。モデルは以前の実行を覚えていません)。
安全性
- デフォルトで機密情報を添付しない(
.env、キーファイル、認証トークン)。積極的に編集し、必要なものだけを共有する。 - 「必要最低限のコンテキスト」を優先:ファイル数が少なく、より良いプロンプトは、リポジトリ全体のダンプよりも優れています。