Start

Quickstart

GitHub Edit page

This walks through the minimum to get a useful answer back. If you haven't installed Oracle yet, start with Install.

#1. Pick a mode

ModeWhen to use itWhat you need
APIYou have an API key and want reliability + multi-model.OPENAI_API_KEY (or Gemini / Anthropic).
BrowserYou have a ChatGPT Plus/Pro account and want GPT-5.5 Pro for free.Chrome on macOS / Linux / Windows.
RenderAir-gapped review, paste into the model of your choice.Just Oracle.

If both are available Oracle picks API by default (cheaper to short-circuit). Override per-run with --engine browser.

#2. Your first run

#API mode

export OPENAI_API_KEY=sk-...
oracle -p "Audit the storage layer for race conditions" \
  --file "src/storage/**/*.ts" \
  --file "!**/*.test.ts"

Oracle prints the assistant's reply on stdout and stores the run under ~/.oracle/sessions/<id>/.

#Browser mode (no API key)

First run — log in once, browser stays open:

oracle --engine browser --browser-manual-login \
  --browser-keep-browser --browser-input-timeout 120000 \
  -p "HI"

Subsequent runs reuse the saved profile:

oracle --engine browser --browser-manual-login \
  --browser-auto-reattach-delay 5s \
  --browser-auto-reattach-interval 3s \
  --browser-auto-reattach-timeout 60s \
  -p "Audit the storage layer for race conditions" \
  --file "src/storage/**/*.ts"

--browser-manual-login skips Keychain cookie copy (no permission popups) and reuses a persistent automation profile under ~/.oracle/browser/.

#Render and copy

oracle --render --copy -p "Architecture review" --file "src/**/*.ts"

The bundle is on your clipboard. Paste it into ChatGPT, Claude, Gemini, AI Studio, or wherever you want the answer.

#3. Preview before you spend

oracle --dry-run summary --files-report \
  -p "Audit the storage layer for race conditions" \
  --file "src/**/*.ts"

--dry-run summary lists token counts per file plus the assembled prompt size. Use it to spot a runaway directory before sending. --dry-run full prints the entire bundle; --dry-run json is structured for tools.

#4. Multi-model cross-check

oracle -p "Cross-check the data layer assumptions" \
  --models gpt-5.5-pro,gemini-3-pro,claude-4.6-sonnet \
  --file "src/**/*.ts"

One command, three providers. Oracle aggregates cost and token usage per model. See Multi-model for output formats and Mythical Pro Agents for picking the right combo.

#5. Reattach to a long run

GPT-5.x Pro replies can take 10 minutes to over an hour. API runs detach by default; reattach later:

oracle status --hours 24
oracle session <id> --render

For browser runs, --browser-auto-reattach-* polls the existing ChatGPT tab when the page redirects mid-load. See Sessions for the full lifecycle.

#6. Wire it into your coding agent

Drop this in AGENTS.md or CLAUDE.md:

- Oracle bundles a prompt plus the right files so a Pro model (GPT-5.5 Pro, Gemini 3 Pro, Claude Opus) can answer. Use when stuck, debugging, or reviewing.
- Run `npx -y @steipete/oracle --help` once per session before first use.

Or wire MCP — see MCP and Agents.

#Where to go next