Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).
npxskills add openclaw/openclaw--skill oracleLoading…
Oracle bundles a prompt + selected files for one second-model pass. Treat output as advisory; verify against code + tests.
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:
--dry-run summary --files-report--engine browser --model gpt-5.5-pro--engine api --model gpt-5.5--dry-run + --files-report).Help:
oracle --helpnpx -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/**"--copy is a hidden alias for --copy-markdown.--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.mdExclude:
--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"Defaults (implementation behavior):
node_modules, dist, coverage, .git, .turbo, .next, build, tmp (skipped unless explicitly passed as literal dirs/files)..gitignore when expanding globs.--file ".github/**").api when OPENAI_API_KEY is set; otherwise browser.--engine api for Claude/Grok/Codex or multi-model runs.--browser-attachments auto|never|always (auto pastes inline up to ~60k chars then uploads).oracle serve --host 0.0.0.0 --port 9473 --token <secret>oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"~/.oracle/sessions (override with ORACLE_HOME_DIR).oracle status --hours 72oracle session <id> --render--slug "<3-5 words>" to keep session IDs readable.--force only when you truly want a fresh run.Oracle starts with zero project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or "obvious" paths. Include:
.env, key files, auth tokens). Redact aggressively; share only what's required.For long investigations, write a standalone prompt + file set so you can rerun days later:
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).
Feishu document read/write operations. Activate when user mentions Feishu docs, cloud docs, or docx links.
OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Feishu document read/write operations. Activate when user mentions Feishu docs, cloud docs, or docx links.
OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.