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.

oracle