Communityコーディング&開発github.com

steipete/oracle

Oracleによるセカンドモデルレビュー:プロンプトとファイルをバンドルし、デバッグ、リファクタリング、設計を支援します。

oracle とは?

Oracleは、AIエージェントのスキルとして、プロンプトと選択したファイルを一つにまとめ、別のモデル(主にGPT-5.5 Pro)にワンショットで送信することで、リポジトリのコンテキストを考慮したアドバイスを得るためのツールです。主にブラウザ経由のワークフロー(ChatGPT)を想定しており、長時間実行されるセッションを管理します。API経由での使用も可能で、マルチモデル実行やClaude、Geminiなどのサポートも行います。デフォルトで特定のディレクトリやファイルを除外し、トークン数やコストを事前に確認できる機能、パフォーマンストレース、セッションの再アタッチなど、実用的な機能を備えています。開発者は、`--file`オプションで柔軟にファイルを指定し、`--dry-run`で送信内容をプレビューした上で、ブラウザまたはAPIエンジンを選択して実行できます。

対応✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/oracle

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 + 除外指定。機密情報は避ける。

黄金のパス(高速かつ信頼性)

  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 を起動時間と最初の出力時間の計測に使用。トレースはプロンプト、トークン、キー、クッキー、インラインのクッキーペイロードを編集します。デタッチされた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-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期限です。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 build
    • node ~/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、キーファイル、認証トークン)。積極的に編集し、必要なものだけを共有する。
  • 「必要最低限のコンテキスト」を優先:ファイル数が少なく、より良いプロンプトは、リポジトリ全体のダンプよりも優れています。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

関連スキル