Oracle

Oracle (CLI) — best use

Oracle bundles a prompt and selected files into a one-shot request so another model can answer with real repository context through the API or browser. A prompt is required; attach files only when they add necessary context. Treat responses as advisory and verify them against the codebase and tests.

Main use case (browser, GPT-5.6)

Use browser mode with GPT-5.6 when the ChatGPT account exposes it. GPT-5.6 Sol and GPT-5.6 Sol Pro are distinct targets: base Sol uses the Extra High effort setting, while Pro is a separate picker target for difficult or long-running work.

Recommended defaults:

• Engine: browser (--engine browser)
• Base Sol: --model gpt-5.6-sol
• Base Sol maximum reasoning: --browser-thinking-time extra-high (Extra High)
• Explicit Pro effort on GPT-5.6 Sol: --browser-thinking-time pro (fails closed if Pro cannot be confirmed)
• Browser GPT-5.5 with Pro effort: --model gpt-5.5 --browser-thinking-time pro
• API Pro maximum reasoning: --model gpt-5.6-sol --reasoning-mode pro --reasoning-effort max
• Fallback: explicitly use --model gpt-5.5-pro when GPT-5.6 is unavailable
• Attachments: directories/globs plus excludes; never attach secrets by default

GPT-5.6 availability is account-dependent. Confirm the base Sol picker and retain model-selection evidence. A bare Pro picker label proves picker selection but does not, by itself, prove the server-side Pro generation.

GPT-5.6 model selection

This version supports GPT-5.6 on both surfaces, but Pro selection differs:

• gpt-5.6: follow the GPT-5.6 family default
• gpt-5.6-sol: pin ChatGPT's GPT-5.6 Sol entry
• Browser: gpt-5-pro selects ChatGPT's Pro target
• API: --reasoning-mode pro enables Pro execution on gpt-5.6-sol; pair it with --reasoning-effort max for maximum reasoning

For base Sol, use:

oracle --engine browser --browser-manual-login --model gpt-5.6-sol \
  --browser-thinking-time extra-high \
  -p "<task>" --file "src/**"

For GPT-5.6 Sol Pro through the Responses API, use:

oracle --engine api --model gpt-5.6-sol \
  --reasoning-mode pro \
  --reasoning-effort max \
  -p "<task>" --file "src/**"

Do not use --model "GPT-5.6 Sol Pro". Pro is intentionally handled as a browser picker target and an API reasoning mode. Browser label validation rejects unknown future variants such as gpt-5.6-luna instead of silently falling back to Sol; API runs preserve such provider model IDs unchanged.

Browser mode maps these aliases to ChatGPT's Sol picker. API and multi-model runs preserve the corresponding first-party OpenAI model IDs; provider-qualified and unrelated custom IDs remain pass-through values.

The GPT-5.6 browser support depends on the unified Intelligence picker. It recognizes the current English and Chinese effort labels, avoids matching 高 inside 极高, and re-queries the composer pill after React replaces it so selection verification cannot rely on a detached stale node.

Compatibility with npm 0.15.2

Do not pass gpt-5.6 or gpt-5.6-sol to an unpatched npm 0.15.2 install. That release can normalize those labels to gpt-5.2. Use the explicit fallback:

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

After upgrading to a release containing the GPT-5.6 model-selection and unified-picker changes, verify all of the following before removing the fallback guidance: --help --verbose exposes the new options, browser dry-run resolves both aliases to GPT-5.6 Sol, API routing selects first-party OpenAI, and a live browser run records strict GPT-5.6 selection evidence.

Golden path

1. Pick the smallest file set that still contains the truth.
2. Preview the bundle with --dry-run and --files-report.
3. Use browser mode for GPT-5.6; use API only when explicitly intended.
4. If a run detaches or times out, reattach to the stored session instead of starting a duplicate.

Commands

• Show help:

  • npx -y @steipete/oracle --help --verbose

• Preview without calling a model:

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

• Inspect token usage:

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

• Browser run:

  • oracle --engine browser --browser-manual-login --model gpt-5.6-sol --browser-thinking-time extra-high -p "<task>" --file "src/**"

• Manual paste fallback:

  • npx -y @steipete/oracle --render-markdown --copy-markdown -p "<task>" --file "src/**"
  • --render is an alias for --render-markdown.

• Performance trace:

  • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"

Attaching files

--file accepts files, directories, and globs. Pass it multiple times or use comma-separated entries.

• Include: --file "src/**", --file src/index.ts, --file docs --file README.md
• Exclude: prefix a pattern with !, for example --file "!src/**/*.test.ts"
• Default ignored directories: node_modules, dist, coverage, .git, .turbo, .next, build, and tmp
• Globs honor .gitignore and do not follow symlinks.
• Dotfiles require an explicit dot-segment in the pattern, such as --file ".github/**".
• Files over 1 MB are rejected by default; configure ORACLE_MAX_FILE_SIZE_BYTES or maxFileSizeBytes when necessary.

Keep total input under roughly 196k tokens. Use --files-report or --dry-run json to identify oversized inputs. Never attach .env files, private keys, auth tokens, or other secrets unless they have been redacted and are essential to the question.

Engines and browser controls

• Auto-selection uses API when OPENAI_API_KEY is set and browser otherwise.
• Browser supports GPT models through ChatGPT and Gemini models through Gemini web. API-only models include gpt-5.1-codex.
• Current model families include GPT-5.5/5.4/5.2/5.1, Gemini 3.x, and Claude 4.x; availability depends on engine and provider.
• API runs require explicit user consent because they may incur usage costs.
• Browser attachments use --browser-attachments auto|never|always.
• Browser uploads keep one text/source file native and bundle multiple text/source files. auto keeps flattened text for text-only uploads; use --browser-bundle-format zip for a filesystem tree, or --browser-bundle-files to force every resolved attachment into one bundle.
• Reuse an existing Chrome session with --browser-tab <ref>, --browser-attach-running, or --remote-chrome <host:port>.
• Use --browser-model-strategy select|current|ignore to control picker behavior.
• Use --browser-follow-up "<prompt>" for another turn in the same browser conversation, or --followup <sessionId|responseId> for a stored run.
• Use --browser-research deep only when Deep Research is explicitly wanted.

API preflight

Before an API run, check provider readiness without printing secrets:

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

Use --provider openai or --no-azure when first-party OpenAI routing is required. For multi-model panels where partial success is useful, use --allow-partial --write-output <path> so successful outputs and the manifest can be recovered.

Set an explicit deadline for automation, for example --timeout 10m; Oracle derives the HTTP timeout unless --http-timeout is supplied.

Sessions and recovery

• Sessions are stored under ~/.oracle/sessions; override with ORACLE_HOME_DIR.
• Browser artifacts include transcript.md and, when available, research reports and generated images.
• List recent sessions with oracle status --hours 72.
• Attach with oracle session <id> --render.
• Use --slug "<3-5 words>" for readable session IDs.
• If a run times out, reattach; do not re-run it. Use --force only when a genuinely new identical run is intended.
• Successful non-project browser one-shots are archived automatically by default; override with --browser-archive never|always.

Prompt template

Oracle starts with zero project knowledge. Include:

• Project briefing: stack, services, build/test commands, and platform constraints
• Where things live: entrypoints, configs, key modules, and dependency boundaries
• Exact question, prior attempts, and verbatim error text
• Constraints such as API compatibility, performance budgets, and files not to change
• Desired output such as a patch plan, tests, risk list, or tradeoff comparison

For a long investigation, make the prompt restorable: put a 6–30 sentence briefing at the top, concrete reproduction and errors in the middle, and attach all context files required by a fresh model at the bottom. Oracle runs are one-shot; the model does not remember prior runs.