| name | oracle |
| description | Use the @steipete/oracle CLI to bundle a prompt plus the right files and get a second-model review (API or browser) for debugging, refactors, design checks, or cross-validation. |
Oracle (CLI)
Oracle 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 use case (browser)
Default workflow: --engine browser with GPT in ChatGPT.
Golden path
- Pick a tight file set (fewest files that still contain the truth).
- Preview what you're about to send (
--dry-run + --files-report).
- Run in browser mode for the usual ChatGPT workflow; use API only when you explicitly want it.
- If the run detaches/timeouts: reattach to the stored session (don't re-run).
Commands (preferred)
- Show help:
npx -y @steipete/oracle --help
- Preview (no tokens):
npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
- Token/cost sanity:
npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"
- Browser run:
npx -y @steipete/oracle --engine browser -p "<task>" --file "src/**"
- Manual paste fallback:
npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"
Attaching files (--file)
- Include:
--file "src/**", --file src/index.ts
- Exclude:
--file "!src/**/*.test.ts"
- Default-ignored dirs:
node_modules, dist, coverage, .git, etc.
- Hard cap: files > 1 MB are rejected.
Budget + observability
- Target: keep total input under ~196k tokens.
- Use
--files-report to spot token hogs before spending.
Sessions
- Stored under
~/.oracle/sessions.
- List:
oracle status --hours 72
- Attach:
oracle session <id> --render
- Use
--slug "<3-5 words>" for readable session IDs.
Safety
- Don't attach secrets by default.
- Prefer "just enough context": fewer files + better prompt beats whole-repo dumps.
