Skill

Fail

Audit score 45

oracle

steipete/clawdis

Second-model code review, debug, and refactor with file selection, token preview, and API or browser execution.

What is oracle?

Oracle bundles a prompt and selected files for a single second-model pass via OpenAI API or browser. Use it to review code, debug issues, refactor, or design solutions. Treat output as advisory and verify against your code and tests.

Preview payload and token spend before running with --dry-run
Select tight file sets with glob patterns and exclusions
Run via browser (GPT/Gemini, long-running) or API (Claude, Grok, multi-model)
Store and reattach long-running sessions without re-running
Render prompts to markdown for manual pasting as fallback
Exclude defaults (node_modules, dist, .git, etc.) and honor .gitignore

How to install oracle

npx skills add https://github.com/steipete/clawdis --skill oracle

Prerequisites

Node.js installed
OPENAI_API_KEY set (for API engine) or browser access to ChatGPT/Gemini (for browser engine)
oracle binary installed via: npx skills add https://github.com/steipete/clawdis --skill oracle

Claude Code

Cursor

Windsurf

Cline

How to use oracle

1.Run oracle --help to see all options
2.Preview your payload: oracle --dry-run summary -p "<task>" --file "src/**"
3.Check token cost: oracle --dry-run summary --files-report -p "<task>" --file "src/**"
4.Execute via browser: oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"
5.If the run detaches, reattach with: oracle session <id> --render (do not re-run)

Use cases

Good for

Get a second opinion on code changes before committing
Debug a failing test or error by bundling relevant source files and error text
Refactor a module with full context of dependencies and constraints
Design a solution by describing the problem, stack, and desired output
Review security or performance across selected files with specific guidance

Who it's for

Individual developers seeking code review without human reviewers
Teams using Claude Code or Cursor for agent-assisted development
Engineers debugging complex issues across multiple files
Architects designing solutions with AI assistance

oracle FAQ

What's the difference between --engine api and --engine browser?

API engine uses OPENAI_API_KEY or Azure config and supports Claude, Grok, and multi-model runs. Browser engine works with GPT and Gemini only but is useful for long ChatGPT Pro thinking sessions. Auto-picks API if OPENAI_API_KEY is set; otherwise browser.

How do I avoid re-running a long session that timed out?

Sessions are stored in ~/.oracle/sessions. List them with oracle status --hours 72, then reattach with oracle session <id> --render. Do not blindly re-run; reattach instead.

What files should I include in --file?

Pick the tightest set that contains the truth: source files, configs, and key dependencies. Use globs like --file "src/**" and exclude tests/snapshots with --file "!**/*.test.*". Defaults skip node_modules, dist, .git, and honor .gitignore.

How do I write an effective prompt for Oracle?

Assume zero project knowledge. Include: project briefing (stack, build commands), where things live (directories, entrypoints), exact question + error text, constraints, and desired output format. Attach only necessary files; redact secrets aggressively.

Can I use Oracle with models other than GPT?

Yes, but only via --engine api. Browser engine supports GPT and Gemini only. Use --engine api --model <name> for Claude, Grok, or other models with appropriate API keys configured.

Full instructions (SKILL.md)

Source of truth, from steipete/clawdis.

name: oracle description: "Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine." homepage: https://askoracle.dev metadata: { "openclaw": { "emoji": "🧿", "requires": { "bins": ["oracle"] }, "install": [ { "id": "node", "kind": "node", "package": "@steipete/oracle", "bins": ["oracle"], "label": "Install oracle (node)", }, ], }, }

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

Pick a tight file set (fewest files that still contain the truth).
Preview payload + token spend (--dry-run + --files-report).
Use browser mode for long Pro thinking; API mode for explicit API calls.
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" (key directories, entrypoints, config files, boundaries).
Exact question + what you tried + the error text (verbatim).
Constraints ("don't change X", "must keep public API", etc).
Desired output ("return patch plan + tests", "give 3 options with tradeoffs").

Safety

Don't attach secrets by default (.env, key files, auth tokens). Redact aggressively; share only what's required.

"Exhaustive prompt" restoration pattern

For long investigations, write a standalone prompt + file set so you can rerun days later:

6-30 sentence project briefing + the goal.
Repro steps + exact errors + what you tried.
Attach all context files needed (entrypoints, configs, key modules, docs).

Oracle runs are one-shot; the model doesn't remember prior runs. "Restoring context" means re-running with the same prompt + --file … set (or reattaching a still-running stored session).