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.