oracle

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:

1. Check serve is running: launchctl list | grep oracle
2. Restart: launchctl stop com.oracle.serve && launchctl start com.oracle.serve
3. Login needed: open http://127.0.0.1:9473 — Chrome window should appear, login to ChatGPT once
4. 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 (global)
npm install -g @steipete/oracle

# Homebrew
brew install steipete/tap/oracle

# One-shot (no install)
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                      # List sessions
oracle session <id> --render       # Replay a session
oracle status --clear --hours 168  # Prune old sessions

Remote browser service:

# Host (signed-in Chrome)
oracle serve --host 0.0.0.0:9473 --token secret123

# Client
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/folder
• browser.thinkingTime / browser.manualLogin — browser defaults
• browser.remoteHost / browser.remoteToken — remote service connection
• browser.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