Oracle
Get a second LLM to review, debug, refactor, or design against a minimal file set before you merge or ship.
Overview
Oracle is an agent skill most often used in Ship (also Build integrations, Operate errors) that runs the Oracle CLI for second-model review, debug, refactor, and design on selected files with dry-run token checks.
Install
npx skills add https://github.com/steipete/clawdis --skill oracleWhat is this skill?
- Bundles prompt plus selected files for one second-model pass (treat output as advisory)
- Dry-run summary and --files-report to preview payload and token spend before spending
- Browser engine for long gpt-5.5-pro runs; API engine when OPENAI_API_KEY or Azure is configured
- Golden path: tight file set → preview → run → reattach on timeout instead of blind re-run
- CLI install via npm @steipete/oracle or npx -y @steipete/oracle when binary missing
- Default browser model documented as gpt-5.5-pro; API default gpt-5.5
- Golden path is 4 numbered steps including reattach-on-timeout
Adoption & trust: 1.9k installs on skills.sh; 378k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need a credible second opinion on a tight code change without dumping the repo or burning tokens on a blind full-context run.
Who is it for?
Solo builders who already use Claude Code or similar agents and want a disciplined second-model review CLI with dry-run and browser/API engine choice.
Skip if: Teams that forbid external LLM APIs on code, or anyone treating Oracle output as merge-ready without local tests and primary-agent follow-up.
When should I use this skill?
You want second-model review, debug, refactor, or design on selected files with Oracle CLI dry-run and engine choice.
What do I get? / Deliverables
You get a scoped second-model advisory pass with previewed token cost and a recoverable session if the run detaches—then you verify fixes in your own tests and primary agent.
- Second-model advisory text for the scoped file set
- Dry-run summary and files report when preview flags are used
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Oracle is framed as second-model review and debug with advisory output you verify in tests—canonical shelf is Ship review. Dry-run previews and detached-session reattach support pre-merge and pre-release code review workflows.
Where it fits
Package a few integration modules and ask Oracle to sanity-check error handling before you wire the feature end-to-end.
Dry-run token spend on the diff’s core files, then run browser-mode review before opening the PR.
Send auth-related files for advisory refactor notes, then confirm findings with your own security checklist.
Attach stack-trace and handler files for second-model debug hypotheses during a production incident.
How it compares
Use instead of ad-hoc copy-paste into a separate chat when you need file-scoped second-model review with token preview—not a replacement for your test suite or security scanner.
Common Questions / FAQ
Who is oracle for?
Indie and solo developers shipping with agentic IDEs who want a second model to review or debug specific files via a dedicated CLI.
When should I use oracle?
During Ship review before merge, while debugging tricky changes in Build, or when validating refactor/design choices in Operate-style incident triage—always after selecting the smallest file set that contains the truth.
Is oracle safe to install?
It requires the oracle binary, filesystem reads for selected files, and network for API or browser engines; review the Security Audits panel on this Prism page and treat third-party model calls as sensitive if your repo includes secrets.
SKILL.md
READMESKILL.md - Oracle
# oracle Oracle bundles a prompt + selected files for one second-model pass. Treat output as advisory; verify against code + tests. ## Main path Current CLI default model: `gpt-5.5-pro`. Browser engine is useful for long ChatGPT Pro runs; API engine is useful when `OPENAI_API_KEY` or Azure config is ready. Recommended defaults: - Preview first: `--dry-run summary --files-report` - Browser long run: `--engine browser --model gpt-5.5-pro` - API explicit: `--engine api --model gpt-5.5` ## Golden path 1. Pick a tight file set (fewest files that still contain the truth). 2. Preview payload + token spend (`--dry-run` + `--files-report`). 3. Use browser mode for long Pro thinking; API mode for explicit API calls. 4. If the run detaches/timeouts: reattach to the stored session. Do not blindly re-run. ## Commands (preferred) - Help: - `oracle --help` - If the binary isn't installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings). - Preview (no tokens): - `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"` - `oracle --dry-run full -p "<task>" --file "src/**"` - Token sanity: - `oracle --dry-run summary --files-report -p "<task>" --file "src/**"` - Browser run (main path; long-running is normal): - `oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"` - Manual paste fallback: - `oracle --render --copy -p "<task>" --file "src/**"` - Note: `--copy` is a hidden alias for `--copy-markdown`. ## Attaching files (`--file`) `--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated. - Include: - `--file "src/**"` - `--file src/index.ts` - `--file docs --file README.md` - Exclude: - `--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"` - Defaults (implementation behavior): - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless explicitly passed as literal dirs/files). - Honors `.gitignore` when expanding globs. - Does not follow symlinks. - Dotfiles filtered unless opted in via pattern (e.g. `--file ".github/**"`). - Files > 1 MB rejected. ## Engines (API vs browser) - Auto-pick: `api` when `OPENAI_API_KEY` is set; otherwise `browser`. - Browser supports GPT + Gemini only; use `--engine api` for Claude/Grok/Codex or multi-model runs. - Browser attachments: - `--browser-attachments auto|never|always` (auto pastes inline up to ~60k chars then uploads). - Remote browser host: - Host: `oracle serve --host 0.0.0.0 --port 9473 --token <secret>` - Client: `oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"` ## Sessions + slugs - Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`). - Runs may detach or take a long time (browser + Pro often does). If the CLI times out: do not re-run; reattach. - List: `oracle status --hours 72` - Attach: `oracle session <id> --render` - Use `--slug "<3-5 words>"` to keep session IDs readable. - Duplicate prompt guard exists; use `--force` only when you truly want a fresh run. ## Prompt template (high signal) Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or "obvious" paths. Include: - Project briefing (stack + build/test commands + platform constraints). - "Where things live"