Oracle gives your agents a simple, reliable way to bundle a prompt plus the right files and hand them to another AI. It currently speaks GPT-5.1 and GPT-5 Pro; Pro runs can take up to ten minutes and often return remarkably strong answers.
- API engine — Calls the OpenAI Responses API. Needs
OPENAI_API_KEY. - Browser engine — Automates ChatGPT in Chrome so you can use your Pro account directly. Toggle with
--engine browser; no API key required. - Gemini engine (experimental) — Uses the same Chrome automation stack but targets Gemini in your signed-in Google profile via
--engine gemini.
If you omit --engine, Oracle prefers the API engine when OPENAI_API_KEY is present; otherwise it falls back to browser mode. Switch explicitly with -e, --engine {api|browser|gemini} when you want to override the auto choice. Everything else (prompt assembly, file handling, session logging) stays the same.
# One-off (no install)
OPENAI_API_KEY=sk-... npx -y @steipete/oracle -p "Summarize the risk register" --file docs/risk-register.md docs/risk-matrix.md
# Browser engine (no API key)
npx -y @steipete/oracle --engine browser -p "Summarize the risk register" --file docs/risk-register.md docs/risk-matrix.md
# Globs/exclusions
npx -y @steipete/oracle -p "Review the TS data layer" --file "src/**/*.ts" --file "!src/**/*.test.ts"
# Mixed glob + single file
npx -y @steipete/oracle -p "Audit data layer" --file "src/**/*.ts" --file README.md
# Inspect past sessions
oracle status --clear --hours 168 # prune a week of cached runs
oracle status # list runs; grab an ID
oracle session <id> # replay a run locally- One-liner in CI —
OPENAI_API_KEY=sk-... npx -y @steipete/oracle --prompt "Smoke-check latest PR" --file src/ docs/ --preview summary(add to your pipeline as a non-blocking report step). - Package script — In
package.json:"oracle": "oracle --prompt \"Review the diff\" --file ."then runOPENAI_API_KEY=... pnpm oracle.
- Bundle once, reuse anywhere — Prompt + files become a markdown package the model can cite.
- Flexible file selection — Glob patterns and
!excludes let you scoop up or skip files without scripting. - Pro-friendly — GPT-5 Pro background runs stay alive for ~10 minutes with reconnection + token/cost tracking.
- Two paths, one UX — API or browser, same flags and session logs.
- Search on by default — The model can ground answers with fresh citations.
- File safety — Per-file token accounting and size guards;
--files-reportshows exactly what you’re sending. - Readable previews —
--preview/--render-markdownlet you inspect the bundle before spending.
| Flag | Purpose |
|---|---|
-p, --prompt <text> |
Required prompt. |
-f, --file <paths...> |
Attach files/dirs (supports globs and ! excludes). |
| `-e, --engine <api | browser |
-m, --model <name> |
gpt-5-pro (default) or gpt-5.1. |
--files-report |
Print per-file token usage. |
| `--preview [summary | json |
--render-markdown |
Print the assembled [SYSTEM]/[USER]/[FILE] bundle. |
-v, --verbose |
Extra logging (also surfaces advanced flags with --help). |
More knobs (--max-input, cookie sync controls for browser mode, etc.) live behind oracle --help --verbose.
Every non-preview run writes to ~/.oracle/sessions/<slug> with usage, cost hints, and logs. Use oracle status to list sessions, oracle session <id> to replay, and oracle status --clear --hours 168 to prune. Set ORACLE_HOME_DIR to relocate storage.
pnpm test
pnpm test:coverageIf you’re looking for an even more powerful context-management tool, check out https://repoprompt.com
Name inspired by: https://ampcode.com/news/oracle