Oracle

Oracle - Unified Technical Advisor

Two complementary modes for different types of questions.

Routing Decision

Ask: "Is the truth external, or is it in our code?"

Commands

Script root: ${CLAUDE_PLUGIN_ROOT}/skills/oracle/scripts

Repo Oracle (codebase exploration)

bun ${CLAUDE_PLUGIN_ROOT}/skills/oracle/scripts/oracle.ts "question"

Capabilities: Explores files, runs commands, searches web (read-only sandbox).

Web Oracle (@steipete/oracle CLI)

The CLI 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.

Main workflow: --engine browser with GPT-5.2 Pro in ChatGPT. This is the "human in the loop" path — it can take ~10 minutes to ~1 hour; expect a stored session you can reattach to.

Quick reference

# Default: 5.2 Thinking with Heavy reasoning (fast questions)
npx -y @steipete/oracle --engine browser --model "5.2 Thinking" --browser-thinking-time heavy -p "question"

# Escalation: gpt-5.2-pro (Deep Research - complex multi-source research)
npx -y @steipete/oracle --engine browser --model gpt-5.2-pro -p "question"

# Include repo context (curated files)
npx -y @steipete/oracle --engine browser --model "5.2 Thinking" --browser-thinking-time heavy \
  --file "src/auth/**/*.ts" \
  --file "!**/*.test.ts" \
  -p "question with context"

Preview & dry-run (no tokens spent)

Always preview before large runs to check token budget and file selection.

# Summary preview
npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"

# Full preview
npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"

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

Attaching files (--file)

--file accepts files, directories, and globs. Pass multiple times; entries can be comma-separated.

• Include: --file "src/**" | --file src/index.ts | --file docs --file README.md
• Exclude (prefix with !): --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
• Default-ignored dirs: node_modules, dist, coverage, .git, .turbo, .next, build, tmp
• Honors .gitignore when expanding globs
• Does not follow symlinks
• Dotfiles filtered unless explicitly included (e.g. --file ".github/**")
• Hard cap: files > 1 MB are rejected — narrow the match or split files

Budget target: keep total input under ~196k tokens. Use --files-report to spot token hogs before spending.

Engines (API vs browser)

• Auto-pick: uses api when OPENAI_API_KEY is set, otherwise browser.
• Browser engine supports GPT + Gemini only; use --engine api for Claude/Grok/Codex or multi-model runs.
• API runs require explicit user consent before starting because they incur usage costs.
• Browser attachments: --browser-attachments auto|never|always (auto pastes inline up to ~60k chars then uploads).

Sessions & reattachment

Runs may detach or take a long time (browser + GPT-5.2 Pro often does). If the CLI times out, don't re-run — reattach.

# List recent sessions
oracle status --hours 72

# Reattach to a session
oracle session <id> --render

• Sessions stored under ~/.oracle/sessions (override with ORACLE_HOME_DIR).
• Use --slug "<3-5 words>" to keep session IDs readable.
• Duplicate prompt guard exists; use --force only when you truly want a fresh run.

Manual paste fallback

When browser automation isn't available, assemble the bundle and copy to clipboard:

npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"

Note: --copy is a hidden alias for --copy-markdown.

Parallel Execution

Run both with run_in_background=true, poll with TaskOutput, synthesize results.

When to Use Each Mode

Repo Oracle

Questions where the answer is in the codebase:

• "What's causing this race condition in the queue processor?"
• "Audit the blast radius before I refactor the payment service"
• "Why are tests flaky on CI? Investigate the test setup"
• "Map how a request flows from API route to database"
• "Review the uncommitted changes for issues"

Web Oracle (5.2 Thinking - default)

Questions needing external knowledge with quick turnaround:

• "Drizzle vs Prisma for heavy read loads - what are teams saying?"
• "Current security gotchas with Google OAuth?"
• "Is it worth migrating Next.js pages router to app router now?"
• "Compare Socket.io vs Ably vs Pusher for a team of 3"

Web Oracle (gpt-5.2-pro - escalation)

Complex research requiring multi-source synthesis (expect longer runtimes):

• "Comprehensive analysis of auth patterns for B2B SaaS in 2026"
• "Migration path from Redis to Valkey - gather all community experiences"
• "Full competitive analysis of state management solutions"

Both in Parallel

When comparing your code against current standards:

• "Is our auth middleware following current OWASP guidelines?"
• "Does our error handling match RFC 7807? Review our impl"
• "Are we using this library correctly per current docs?"

Routing When Unclear

If the question type isn't obvious, use AskUserQuestion:

What kind of help do you need?
- Find issues in the current implementation (Repo)
- Research best practices and patterns (Web)
- Compare our implementation against current standards (Both)

Prompt Crafting (Web Oracle)

Oracle starts with zero project knowledge. The model cannot infer your stack, build tooling, conventions, or "obvious" paths. Include:

• Project briefing: stack + build/test commands + platform constraints
• "Where things live": key directories, entrypoints, config files, dependency boundaries
• Exact question: what you tried + the error text (verbatim)
• Constraints: "don't change X", "must keep public API", "perf budget", etc.
• Desired output: "return patch plan + tests", "list risky assumptions", "give 3 options with tradeoffs"

Exhaustive prompt pattern (long investigations)

When you know this will be a deep investigation, write a self-contained prompt:

• Top: 6-30 sentence project briefing + current goal
• Middle: concrete repro steps + exact errors + what you already tried
• Bottom: attach all context files needed so a fresh model can fully understand

If you need to reproduce the same context later, re-run with the same prompt + --file set (Oracle runs are one-shot; the model doesn't remember prior runs).

Second Opinion Workflow

Best practice from developer research: review diffs and tests, not raw code.

1. Generate changes (primary agent writes code)
2. Package context for review (diff + key files + test results)
3. Review with oracle (critique: bugs, edge cases, missing tests)
4. Apply fixes + run tests
5. Repeat until critique converges

Effective review questions:

• "Review the current diff for security issues"
• "What edge cases am I missing in these uncommitted changes?"
• "At the end of this phase, review my work"

Response Format

Both modes return structured responses:

Essential

• Bottom Line: Direct answer (1-2 sentences)
• Action Plan: Numbered next steps
• Effort Estimate: Quick (<1h) | Short (1-4h) | Medium (1-2d) | Large (3d+)

Expanded (when relevant)

• Reasoning: Why this approach
• Trade-offs: Gains vs sacrifices
• Dependencies: Prerequisites

Edge Cases (when applicable)

• Escalation Triggers: When to reconsider
• Alternatives: Backup options
• Gotchas: Common mistakes

Background Execution

For deep analysis, run in background:

# Repo Oracle (use run_in_background=true)
bun ${CLAUDE_PLUGIN_ROOT}/skills/oracle/scripts/oracle.ts "Audit this codebase for security issues"

# Web Oracle (use run_in_background=true)
npx -y @steipete/oracle --engine browser --model gpt-5.2-pro -p "Audit auth patterns" --file "src/auth/**"

# Poll
TaskOutput with block=false

# Get result (avoid context flooding)
tail -100 /path/to/output

Safety

• Don't attach secrets (.env, key files, auth tokens). Redact aggressively; share only what's required.
• Prefer "just enough context": fewer files + better prompt beats whole-repo dumps.
• API runs require explicit user consent before starting (they incur costs).

Model Selection Summary