oracle

• You want to ask a large AI model (GPT‑5.2 Pro, Gemini, Claude, etc.) a deep question about your codebase and need it to see the relevant source files, not just a snippet.
• You need a "long think" run — tasks that take 10 minutes to an hour — and want a stored session you can reattach to if the CLI times out.
• You need to control exactly which files are bundled (via globs, exclusions, and .gitignore awareness) to keep token spend predictable.
• You want to preview the full payload and token cost with --dry-run before sending anything to a model.

• You need real-time, multi-turn conversational context across many back-and-forth exchanges — oracle runs are one-shot; prior runs are not remembered without reattaching a stored session.
• You want to use a model other than GPT or Gemini via the browser engine — those require --engine api (Claude, Grok, Codex, etc.).
• Your context files exceed 1 MB each — oracle rejects files above that limit.

Oracle merges your prompt with any number of files, directories, or globs into a single request payload. Pass --file multiple times, mix includes and !-prefixed excludes, and oracle intelligently skips node_modules, dist, .git, and other noise directories automatically.

The --engine browser mode drives ChatGPT or Gemini directly in a browser session — ideal for models only accessible via web UI. It auto-decides whether to paste content inline or upload attachments based on size (up to ~60k chars inline, then file upload).

All runs are stored under ~/.oracle/sessions. If a long browser run detaches or times out, use oracle status --hours 72 to list recent sessions and oracle session <id> --render to reattach — no need to re-run and spend tokens again.

Run --dry-run summary or --dry-run full combined with --files-report to inspect exactly what would be sent and estimate token cost before any real request is made. This prevents surprise overruns on large codebases.

When OPENAI_API_KEY is set (or --engine api is explicit), oracle routes through the API instead of the browser. This unlocks Claude, Grok, Codex, and multi-model workflows that the browser engine doesn't support.

Serve a browser automation host on a remote machine with oracle serve --host 0.0.0.0 --port 9473 --token <secret>, then connect any oracle client to it. Useful for offloading long-running browser sessions to a server.

A developer bundles the relevant src/** files with a detailed prompt describing the bug, error text, and constraints, then runs oracle --engine browser --model gpt-5.2-pro. The model receives full context and returns a patch plan. If the session detaches after 20 minutes, the developer reattaches rather than re-running.

Before committing to an expensive run, a developer runs oracle --dry-run summary --files-report -p "<task>" --file "src/**" to see which files would be included and how many tokens they'd consume, then trims the file set before the real run.

When the browser engine isn't suitable, the developer uses oracle --render --copy -p "<task>" --file "src/**" to render the full bundled prompt to the clipboard, then pastes it manually into any chat interface.

For a complex multi-day debugging effort, a developer writes a standalone prompt file with a 6–30 sentence project briefing, repro steps, and exact errors, then attaches all relevant config and entrypoint files. The prompt is self-contained so the same oracle command can be rerun days later with identical context.