| name | oracle |
| description | [WHAT] Route prompts + files to GPT-5 Pro, Gemini 3 Pro, Claude Opus 4.1, and more via oracle CLI
[HOW] Uses oracle serve (persistent browser daemon on :9473) or API with OPENAI_API_KEY
[WHEN] Second opinion, multi-model comparison, browser-only features (image gen, extended thinking)
[WHY] Cross-model validation and access to models not available in current context
Triggers: "ask gpt", "oracle", "second opinion", "ask chatgpt", "cross-check with gpt",
"multi-model", "compare models", "gpt-5", "gemini", "use oracle"
|
oracle 🧿
Bundle your prompt and files so another AI can answer with real context. Speaks GPT-5.x, Gemini 3 Pro, Claude Sonnet 4.5, Claude Opus 4.1, and more — via API or browser automation.
Local Setup (THIS MACHINE)
Browser mode is pre-configured. oracle serve runs as a launchd daemon.
Agents just run oracle -p "..." --file ... — config handles routing to serve.
Engine: browser (via oracle serve on 127.0.0.1:9473)
Config: ~/.oracle/config.json (remoteHost + token already set)
Daemon: ~/Library/LaunchAgents/com.oracle.serve.plist
API key: OPENAI_API_KEY in ~/.env.local (source it first)
DO NOT use --engine browser or --browser-manual-login flags directly.
DO NOT try to sniff Chrome cookies — macOS app-bound encryption blocks it.
JUST RUN: oracle -p "your prompt" --file path/to/files
If oracle fails with "unauthorized" or cookie errors:
- Check serve is running:
launchctl list | grep oracle
- Restart:
launchctl stop com.oracle.serve && launchctl start com.oracle.serve
- Login needed: open
http://127.0.0.1:9473 — Chrome window should appear, login to ChatGPT once
- For API mode:
source ~/.env.local && oracle --engine api -p "..."
Repository: steipete/oracle
Homepage: askoracle.dev
Language: TypeScript (95%) · JavaScript (4.2%) · Shell (0.8%)
Stars: 1,235 · License: Other
Latest: v0.8.5 (2026-01-19)
Source Information
This skill synthesizes knowledge from the project README, CHANGELOG, GitHub issues, releases, and file structure — all sourced from the GitHub repository. Confidence is medium across all sources; no conflicting information was detected.
When to Use This Skill
Use this skill when you need to:
- Route a prompt + files to a stronger model — bundle context and send to GPT-5 Pro, Gemini 3 Pro, Claude Opus 4.1, etc.
- Multi-model comparison — run the same prompt against multiple models in one invocation
- Browser automation for ChatGPT/Gemini — when you don't have API keys or need browser-specific features (image generation, thinking time)
- Copy/render bundles — assemble markdown bundles for manual paste into any AI chat
- Session management — track, replay, and reattach to long-running API sessions (GPT-5 Pro detaches by default)
- MCP integration — use Oracle as an MCP server for tool-based AI workflows
- Remote browser service — run
oracle serve on a signed-in host, connect from clients
- Check known issues — browser mode quirks, attachment bugs, platform-specific workarounds
Real-World Triggers
| Scenario | Command Pattern |
|---|
| Get a second opinion from GPT-5 Pro | oracle -p "Review this" --file src/**/*.ts |
| Compare models on the same prompt | oracle --models gpt-5.1-pro,gemini-3-pro -p "..." --file ... |
| No API key, use browser | oracle --engine browser -p "..." --file ... |
| Preview token usage before sending | oracle --dry-run summary -p "..." --file ... |
| Copy bundle for manual paste | oracle --render --copy -p "..." --file ... |
Quick Reference
Installation
npm install -g @steipete/oracle
brew install steipete/tap/oracle
npx -y @steipete/oracle …
Requires Node 22+.
Core Examples
Simple API run (needs OPENAI_API_KEY):
oracle -p "Write an architecture note for the storage adapters" --file src/storage/README.md
Multi-model run:
oracle -p "Cross-check the data layer assumptions" \
--models gpt-5.1-pro,gemini-3-pro \
--file "src/**/*.ts"
Copy bundle for manual paste:
oracle --render --copy \
-p "Review the TS data layer for schema drift" \
--file "src/**/*.ts,*/*.test.ts"
Browser mode (no API key needed):
oracle --engine browser -p "Walk through the UI smoke test" --file "src/**/*.ts"
Dry run preview:
oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md
Gemini browser image generation:
oracle --engine browser --model gemini-3-pro \
-p "a cute robot holding a banana" \
--generate-image out.jpg --aspect 1:1
Session management:
oracle status
oracle session <id> --render
oracle status --clear --hours 168
Remote browser service:
oracle serve --host 0.0.0.0:9473 --token secret123
oracle --engine browser --remote-host localhost:9473 --remote-token secret123 -p "..."
Supported Models
| Model | Type | Notes |
|---|
gpt-5.1-pro | API (default) | Alias to GPT-5.2 Pro |
gpt-5-pro | API | Original GPT-5 Pro |
gpt-5.1 / gpt-5.2 | API | Standard models |
gpt-5.1-codex | API | Codex variant (API-only) |
gpt-5.2-instant / gpt-5.2-pro | API | Speed/quality variants |
gemini-3-pro | API + Browser | Needs GEMINI_API_KEY or Chrome cookies |
claude-4.5-sonnet / claude-4.1-opus | API | Needs ANTHROPIC_API_KEY |
| Any OpenRouter ID | API | e.g., minimax/minimax-m2 |
Key Flags
| Flag | Purpose |
|---|
-p, --prompt <text> | Required prompt |
-f, --file <paths...> | Attach files/dirs (globs + ! excludes) |
-e, --engine <api|browser> | Choose API or browser |
-m, --model <name> | Select model |
--models <list> | Comma-separated models for multi-model runs |
--render, --copy | Print/copy assembled markdown bundle |
--wait | Block for background API runs |
--dry-run [summary|json|full] | Preview without sending |
--write-output <path> | Save final answer to file |
--files-report | Print per-file token usage |
--base-url <url> | Point API at LiteLLM/Azure/OpenRouter |
--browser-model-strategy | select|current|ignore for ChatGPT picker |
--browser-thinking-time | light|standard|extended|heavy |
--browser-manual-login | Reuse persistent automation profile |
--background / --no-background | Force Responses API background mode |
--timeout <seconds|auto> | API deadline (auto = 60m for pro) |
Configuration
Defaults in ~/.oracle/config.json (JSON5). Key settings:
browser.chatgptUrl — target a specific ChatGPT workspace/folderbrowser.thinkingTime / browser.manualLogin — browser defaultsbrowser.remoteHost / browser.remoteToken — remote service connectionbrowser.forceEnglishLocale — opt into --lang/--accept-lang
Environment Variables
| Variable | Purpose |
|---|
OPENAI_API_KEY | GPT-5.x API access |
GEMINI_API_KEY | Gemini 3 Pro API access |
ANTHROPIC_API_KEY | Claude models API access |
ORACLE_HOME_DIR | Override session storage path (~/.oracle/sessions) |
AZURE_OPENAI_* | Azure endpoint configuration |
MCP Integration
Run the stdio server via oracle-mcp. Configure in .mcp.json or via mcporter.
Codex Skill Integration
mkdir -p ~/.codex/skills
cp -R skills/oracle ~/.codex/skills/oracle
Then reference in AGENTS.md/CLAUDE.md.
Key Concepts
- Bundle — Oracle assembles your prompt + files into a single markdown bundle. This bundle is what gets sent to the model (API) or pasted (browser/copy mode).
- Engine —
api (default when keys present) or browser (experimental, uses Chrome automation). API is more reliable.
- Multi-model runs —
--models sends the same bundle to multiple models, aggregating cost/usage.
- Background/detach — GPT-5 Pro API runs detach by default. Use
--wait to block, or oracle session <id> to reattach.
- Sessions — Stored in
~/.oracle/sessions. Replay with oracle session <id> --render. Prune with oracle status --clear.
Known Issues (Open)
| Issue | Summary |
|---|
| #79 | Chrome opens and auto-closes in browser mode |
| #76 | MAX_FILE_SIZE_BYTES not configurable |
| #75 | Browser mode fails during manual login |
| #65 | Browser doesn't select ChatGPT 5.2-pro correctly |
| #68 | MCP consult tool ignores browser config |
| #51 | Windows cookie extraction for Gemini browser |
Platform Notes
- macOS: Browser mode stable
- Linux: May need
--browser-chrome-path / --browser-cookie-path
- Windows: Prefer
--browser-manual-login or inline cookies if decryption is blocked
Working with This Skill
Beginner
Start with --render --copy to see what Oracle bundles, then paste manually. Graduate to API mode once you have keys set up.
Intermediate
Use multi-model runs (--models) to cross-check answers. Use --dry-run to preview token costs. Set up ~/.oracle/config.json for persistent defaults.
Advanced
Deploy oracle serve for remote browser access. Integrate via MCP for tool-based workflows. Use --background with session management for long-running GPT-5 Pro queries.
Available References
| File | Contents | Confidence |
|---|
references/README.md | Full README with installation, usage, flags, integration | Medium |
references/CHANGELOG.md | Version history from v0.7.2 through v0.8.5 | Medium |
references/issues.md | 6 open + 29 closed GitHub issues | Medium |
references/releases.md | 30 releases with detailed notes | Medium |
references/file_structure.md | 342-item repository tree | Medium |
Version History (Recent)
| Version | Date | Highlights |
|---|
| v0.8.5 | 2026-01-19 | Bridge workflow + MCP browser controls, background/zombie flags |
| v0.8.4 | 2026-01-05 | Zod 4.3.5, attachment upload fixes |
| v0.8.3 | 2025-12-31 | Cookie wait, force English locale, attachment hardening |
| v0.8.2 | 2025-12-30 | Release script fixes, test stabilization |
| v0.8.1 | 2025-12-30 | Config defaults for thinkingTime/manualLogin |
