oracle

name: oracle description: Use the @steipete/oracle CLI to bundle a prompt plus the right files and get a second-model review (API or browser) for debugging, refactors, design checks, or cross-validation.

Oracle (CLI) — best use

Oracle bundles your prompt + selected files into one "one-shot" request so another model can answer with real repo context (API or browser automation). Treat outputs as advisory: verify against the codebase + tests.

Recommended Modes (in order of preference)

Option 1: Gemini Browser Mode (RECOMMENDED)

Most reliable browser mode. Uses cookie-based HTTP client (no Chrome automation needed).

# Pre-authorize Keychain first (one-time, enter password and click "Always Allow")
security find-generic-password -s "Chrome Safe Storage" -w

# Run with Gemini
oracle --engine browser --model gemini-3-pro -p "<task>" --file "src/**"

Requirements: Logged into gemini.google.com in Chrome. Close Chrome before first run.

Option 2: ChatGPT Manual Paste

ChatGPT browser automation is unreliable (DevTools connection issues, session token problems). Use --render --copy instead:

# Bundle and copy to clipboard
oracle --render --copy -p "<task>" --file "src/**"

Then manually paste into ChatGPT. This bypasses all browser automation issues.

Option 3: API Mode

Requires API keys but most reliable for programmatic use:

# Set API keys
export OPENAI_API_KEY="your-key"      # For GPT-5.x
export GEMINI_API_KEY="your-key"      # For Gemini
export ANTHROPIC_API_KEY="your-key"   # For Claude

# Run with API
oracle --engine api --model gpt-5.2-pro -p "<task>" --file "src/**"
oracle --engine api --model gemini-3-pro -p "<task>" --file "src/**"
oracle --engine api --model claude-4.5-sonnet -p "<task>" --file "src/**"

Note: API runs require explicit user consent due to usage costs.

Quick Reference

Commands

# Preview (no tokens spent)
oracle --dry-run summary -p "<task>" --file "src/**"

# Token/cost check
oracle --dry-run summary --files-report -p "<task>" --file "src/**"

# Gemini browser (recommended)
oracle --engine browser --model gemini-3-pro -p "<task>" --file "src/**"

# Manual paste for ChatGPT
oracle --render --copy -p "<task>" --file "src/**"

# API mode
oracle --engine api -p "<task>" --file "src/**"

Attaching files (--file)

--file accepts files, directories, and globs. Pass multiple times; comma-separated also works.

Include:

--file "src/**"           # directory glob
--file src/index.ts       # literal file
--file docs --file README.md

Exclude (prefix with negation):

--file "src/**" --file '!src/**/*.test.ts' --file '!**/*.snap'

Defaults:

• Ignores: node_modules, dist, coverage, .git, .turbo, .next, build, tmp
• Honors .gitignore
• Files > 1 MB rejected

Budget

• Target: keep total input under ~196k tokens
• Use --files-report to spot token hogs

Sessions

Sessions stored under ~/.oracle/sessions. If a run detaches:

oracle status --hours 72        # List sessions
oracle session <id> --render    # Reattach

Use --slug "<3-5 words>" for readable session IDs.

Prompt Tips

Oracle starts with zero project knowledge. Include:

• Project briefing (stack, build/test commands)
• Key directories and entrypoints
• Exact error text (verbatim)
• Constraints ("don't change X", "must keep public API")
• Desired output format

Safety

• Don't attach secrets (.env, credentials, auth tokens)
• Prefer minimal context: fewer files + better prompt beats whole-repo dumps

Troubleshooting

macOS Keychain blocks Gemini browser mode

Symptom: Failed to read macOS Keychain (Chrome Safe Storage): Timed out after 3000ms

Fix: Pre-authorize Keychain:

security find-generic-password -s "Chrome Safe Storage" -w
# Enter password, click "Always Allow"

Chrome cookies not found (Gemini)

Symptom: missing __Secure-1PSID/__Secure-1PSIDTS

Fixes:

1. Log into gemini.google.com in Chrome
2. Close Chrome completely before running Oracle
3. Specify profile path if using multiple profiles:

   oracle --engine browser --model gemini-3-pro \
     --browser-cookie-path ~/Library/Application\ Support/Google/Chrome/Profile\ 2/Cookies \
     -p "..." --file "..."
   

ChatGPT browser mode not working

Symptom: Cannot GET /json/list, Inspected target navigated or closed, DevTools errors

Cause: ChatGPT browser automation uses Chrome DevTools Protocol which is unreliable. It launches a new Chrome instance with a temp profile, and session tokens often don't transfer properly.

Solution: Don't use ChatGPT browser mode. Use one of:

1. --render --copy then manually paste into ChatGPT
2. API mode with OPENAI_API_KEY
3. Gemini browser mode instead