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

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

Key Flags

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

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)

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

Version History (Recent)

Generated by Skill Seeker | Enhanced from GitHub repository sources