Oracle bundles your prompt and files so another AI can answer with real context. It speaks GPT-5.1 Pro (default), GPT-5.1 Codex (API-only), GPT-5.1, Gemini 3 Pro, Claude Sonnet 4.5, Claude Opus 4.1, and more—and it can ask one or multiple models in a single run. Browser automation is available; API remains the most reliable path, and --copy is an easy manual fallback.
Install globally: npm install -g @steipete/oracle
# Copy the bundle and paste into ChatGPT
npx @steipete/oracle --render --copy -p "Review the TS data layer for schema drift" --file "src/**/*.ts,*/*.test.ts"
# Minimal API run (expects OPENAI_API_KEY in your env)
npx @steipete/oracle -p "Write a concise architecture note for the storage adapters" --file src/storage/README.md
# Multi-model API run
npx @steipete/oracle -p "Cross-check the data layer assumptions" --models gpt-5.1-pro,gemini-3-pro --file "src/**/*.ts"
# Preview without spending tokens
npx @steipete/oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md
# Browser run (no API key, will open ChatGPT)
npx @steipete/oracle --engine browser -p "Walk through the UI smoke test" --file "src/**/*.ts"
# Sessions (list and replay)
npx @steipete/oracle status --hours 72
npx @steipete/oracle session <id> --render
# TUI (interactive, only for humans)
npx @steipete/oracleEngine auto-picks API when OPENAI_API_KEY is set, otherwise browser; browser is stable on macOS and works on Linux and Windows. On Linux pass --browser-chrome-path/--browser-cookie-path if detection fails; on Windows prefer --browser-manual-login or inline cookies if decryption is blocked.
CLI
- API mode expects API keys in your environment:
OPENAI_API_KEY(GPT-5.x),GEMINI_API_KEY(Gemini 3 Pro),ANTHROPIC_API_KEY(Claude Sonnet 4.5 / Opus 4.1). - Prefer API mode or
--copy+ manual paste; browser automation is experimental. - Browser support: stable on macOS; works on Linux (add
--browser-chrome-path/--browser-cookie-pathwhen needed) and Windows (manual-login or inline cookies recommended when app-bound cookies block decryption). - Remote browser service:
oracle serveon a signed-in host; clients use--remote-host/--remote-token. - AGENTS.md/CLAUDE.md:
- Oracle bundles a prompt plus the right files so another AI (GPT 5 Pro + more) can answer. Use when stuck/bugs/reviewing. - Run `npx -y @steipete/oracle --help` once per session before first use. - Tip: set
browser.chatgptUrlin config (or--chatgpt-url) to a dedicated ChatGPT project folder so browser runs don’t clutter your main history.
MCP
- Run the stdio server via
oracle-mcp. - Configure clients via steipete/mcporter or
.mcp.json; see docs/mcp.md for connection examples.
npx -y @steipete/oracle oracle-mcp- Cursor setup (MCP): drop a
.cursor/mcp.jsonlike below, then pick “oracle” in Cursor’s MCP sources. See https://cursor.com/docs/context/mcp for UI steps.
{
"oracle": {
"command": "oracle-mcp",
"args": []
}
}- Bundle once, reuse anywhere (API or experimental browser).
- Multi-model API runs with aggregated cost/usage, including OpenRouter IDs alongside first-party models.
- Render/copy bundles for manual paste into ChatGPT when automation is blocked.
- GPT‑5 Pro API runs detach by default; reattach via
oracle session <id>/oracle statusor block with--wait. - Azure endpoints supported via
--azure-endpoint/--azure-deployment/--azure-api-versionorAZURE_OPENAI_*envs. - File safety: globs/excludes, size guards,
--files-report. - Sessions you can replay (
oracle status,oracle session <id> --render). - Session logs and bundles live in
~/.oracle/sessions(override withORACLE_HOME_DIR).
| Flag | Purpose |
|---|---|
-p, --prompt <text> |
Required prompt. |
-f, --file <paths...> |
Attach files/dirs (globs + ! excludes). |
-e, --engine <api|browser> |
Choose API or browser (browser is experimental). |
-m, --model <name> |
Built-ins (gpt-5.1-pro default, gpt-5-pro, gpt-5.1, gpt-5.1-codex, gemini-3-pro, claude-4.5-sonnet, claude-4.1-opus) plus any OpenRouter id (e.g., minimax/minimax-m2, openai/gpt-4o-mini). |
--models <list> |
Comma-separated API models (mix built-ins and OpenRouter ids) for multi-model runs. |
--base-url <url> |
Point API runs at LiteLLM/Azure/OpenRouter/etc. |
--chatgpt-url <url> |
Target a ChatGPT workspace/folder (browser). |
--browser-port <port> |
Pin the Chrome DevTools port (WSL/Windows firewall helper). |
| `--browser-inline-cookies[(-file)] <payload | path>` |
--browser-timeout, --browser-input-timeout |
Control overall/browser input timeouts (supports h/m/s/ms). |
--render, --copy |
Print and/or copy the assembled markdown bundle. |
--wait |
Block for background API runs (e.g., GPT‑5.1 Pro) instead of detaching. |
--write-output <path> |
Save only the final answer (multi-model adds .<model>). |
--files-report |
Print per-file token usage. |
--dry-run [summary|json|full] |
Preview without sending. |
--remote-host, --remote-token |
Use a remote oracle serve host (browser). |
--remote-chrome <host:port> |
Attach to an existing remote Chrome session (browser). |
--azure-endpoint, --azure-deployment, --azure-api-version |
Target Azure OpenAI endpoints (picks Azure client automatically). |
Put defaults in ~/.oracle/config.json (JSON5). Example:
{
model: "gpt-5.1-pro",
engine: "api",
filesReport: true,
browser: {
chatgptUrl: "https://chatgpt.com/g/g-p-691edc9fec088191b553a35093da1ea8-oracle/project"
}
}Use browser.chatgptUrl (or the legacy alias browser.url) to target a specific ChatGPT workspace/folder for browser automation.
See docs/configuration.md for precedence and full schema.
Advanced flags
| Area | Flags |
|---|---|
| Browser | --browser-timeout, --browser-input-timeout, --browser-inline-cookies[(-file)], --browser-inline-files, --browser-bundle-files, --browser-keep-browser, --browser-headless, --browser-hide-window, --browser-no-cookie-sync, --browser-allow-cookie-errors, --browser-chrome-path, --browser-cookie-path, --chatgpt-url |
| Azure/OpenAI | --azure-endpoint, --azure-deployment, --azure-api-version, --base-url |
Remote browser example
# Host (signed-in Chrome): launch serve
oracle serve --host 0.0.0.0:9473 --token secret123
# Client: target that host
oracle --engine browser --remote-host 192.168.1.10:9473 --remote-token secret123 -p "Run the UI smoke" --file "src/**/*.ts"
# If cookies can’t sync, pass them inline (JSON/base64)
oracle --engine browser --browser-inline-cookies-file ~/.oracle/cookies.json -p "Run the UI smoke" --file "src/**/*.ts"Session management
# Prune stored sessions (default path ~/.oracle/sessions; override ORACLE_HOME_DIR)
oracle status --clear --hours 168- Browser mode & forks: docs/browser-mode.md (includes
oracle serveremote service), docs/chromium-forks.md, docs/linux.md - MCP: docs/mcp.md
- OpenAI/Azure/OpenRouter endpoints: docs/openai-endpoints.md, docs/openrouter.md
- Manual smokes: docs/manual-tests.md
- Testing: docs/testing.md
If you’re looking for an even more powerful context-management tool, check out https://repoprompt.com
Name inspired by: https://ampcode.com/news/oracle
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
