oracle

name oracle description Strategic technical advisor with two modes. Use for second opinions, architecture decisions, debugging, security analysis, and research. REPO MODE explores your codebase autonomously (finds gaps, reviews code, traces bugs). WEB MODE researches external info via @steipete/oracle CLI (current best practices, library comparisons, docs). Run both in parallel when comparing your implementation against current standards. allowed-tools Bash, TaskOutput, AskUserQuestion 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?" Truth Location Mode Model In our code Repo gpt-5.2 xhigh via Codex SDK External (docs, standards, comparisons) Web 5.2 Thinking + Heavy (default) Complex research needing web synthesis Web gpt-5.2-pro (escalation) Both (compare impl vs standards) Parallel Run both modes 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 Mode Model Use When Repo gpt-5.2 xhigh Codebase questions, finding gaps, code review Web (default) 5.2 Thinking + Heavy External research, best practices, comparisons Web (escalation) gpt-5.2-pro Complex multi-source research, deep synthesis