steipete/oracle
GitHub: steipete/oracle
将 Prompt 与项目文件打包后调用多种大语言模型的开发者命令行工具，支持 API 和浏览器自动化两种模式。
Stars: 3351 | Forks: 339
# oracle 🧿 — Whispering your tokens to the silicon sage
--render
npx -y @steipete/oracle restart
# TUI (interactive, only for humans)
npx -y @steipete/oracle tui
Engine 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.
## Integration
**CLI**
- API mode expects API keys in your environment: `OPENAI_API_KEY` (GPT-5.x), `GEMINI_API_KEY` (Gemini 3.1 Pro / 3.5 Flash / 3.1 Flash-Lite), `ANTHROPIC_API_KEY` (Claude Sonnet 4.6 / Opus 4.1).
- Gemini browser mode uses Chrome cookies instead of an API key—just be logged into `gemini.google.com` in Chrome (no Python/venv required).
- Gemini browser mode accepts explicit `gemini-3.1-flash-lite`, `gemini-3.5-flash`, and `gemini-3.1-pro` IDs. Legacy `gemini-3-pro` browser runs target current Gemini 3.1 Pro. If your account can’t access the requested model, Oracle falls back to 3.1 Flash-Lite and logs the fallback in verbose mode.
- 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-path` when needed) and Windows (manual-login or inline cookies recommended when app-bound cookies block decryption).
- Remote browser service: `oracle serve` on a signed-in host; clients use `--remote-host/--remote-token`.
- Browser artifacts: browser sessions save `transcript.md` and generated artifacts under `~/.oracle/sessions//artifacts/`. Deep Research saves `deep-research-report.md` when the report surface is captured; ChatGPT-generated images and downloadable files are saved with the active browser session when supported file URLs are present.
- MCP image agents: use the `chatgpt_image` tool for the easiest path, or pass `generateImage` to `consult` with `engine: "browser"`; saved paths come back in `structuredContent.images`.
- Browser archiving: by default, successful non-project, non-Deep-Research, non-multi-turn ChatGPT one-shots are archived after local artifacts are saved. Use `--browser-archive never` to disable or `--browser-archive always` to force archiving after a successful browser run. Archived chats remain manageable in ChatGPT.
- Conversation mode guidance: use one-shot browser runs for narrow bug reports or quick file-set reviews; use explicit browser follow-ups for ambiguous architecture/product tradeoffs where a challenge pass and final decision are valuable; use Deep Research for broad public-web questions that need citations. Oracle never invents follow-ups automatically.
- Project Sources: `oracle project-sources list|add --chatgpt-url ` manages the Project Sources tab in ChatGPT browser mode. v1 is append-only (`list`, `add`, `--dry-run`) so agents can share explicit project context without deleting or replacing user sources.
- Fast failure: root runs without a prompt exit nonzero after printing help; `--dry-run` conflicts with `--render` / `--render-markdown`; foreground API runs exit 130 on Ctrl-C while browser cleanup and session recovery still run.
- Performance traces: `--perf-trace` / `ORACLE_PERF_TRACE=1` writes JSON timing marks for startup, root command, first output, and exit. `--perf-trace-path` or `--perf-trace=/tmp/oracle.json` selects the path; detached API children write a session-suffixed sidecar trace.
- 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.chatgptUrl` in config (or `--chatgpt-url`) to a dedicated ChatGPT project folder so browser runs don’t clutter your main history.
**Codex skill**
- Copy the bundled skill from this repo to your Codex skills folder:
- `mkdir -p ~/.codex/skills`
- `cp -R skills/oracle ~/.codex/skills/oracle`
- Then reference it in your `AGENTS.md`/`CLAUDE.md` so Codex loads it.
**MCP**
- Run the stdio server via `oracle-mcp`.
- Configure clients via [steipete/mcporter](https://github.com/steipete/mcporter) or `.mcp.json`; see [docs/mcp.md](docs/mcp.md) for connection examples.
- Claude Code on the same Mac as a signed-in ChatGPT browser can generate a local config directly:
oracle bridge claude-config --local-browser > .mcp.json
- In MCP `consult`, use `preset: "chatgpt-pro-heavy"` for ChatGPT browser mode with `gpt-5.5-pro` and Pro Extended thinking. Add `dryRun: true` to inspect the resolved run without creating a session or touching Chrome.
npx -y @steipete/oracle oracle-mcp
- Cursor setup (MCP): drop a `.cursor/mcp.json` like below, then pick “oracle” in Cursor’s MCP sources. See https://cursor.com/docs/context/mcp for UI steps.
[](https://cursor.com/en-US/install-mcp?name=oracle&config=eyJjb21tYW5kIjoibnB4IC15IEBzdGVpcGV0ZS9vcmFjbGUgb3JhY2xlLW1jcCJ9)
{
"oracle": {
"command": "oracle-mcp",
"args": []
}
}
## Highlights
- Bundle once, reuse anywhere (API or experimental browser).
- Multi-model API runs with aggregated cost/usage, including OpenRouter IDs alongside first-party models.
- Claude Code / MCP browser consults can use the `chatgpt-pro-heavy` preset for a compact ChatGPT Pro second-opinion workflow.
- Render/copy bundles for manual paste into ChatGPT when automation is blocked.
- GPT‑5 Pro API runs detach by default; reattach via `oracle session ` / `oracle status` or block with `--wait`.
- Saved ChatGPT browser conversations and OpenAI/Azure API runs can continue from `--followup `; for multi-model API parents, add `--followup-model `.
- Azure endpoints supported via `--azure-endpoint/--azure-deployment/--azure-api-version` or `AZURE_OPENAI_*` envs; use `--provider openai` / `--no-azure` to force first-party OpenAI when Azure env vars are present.
- Redacted provider checks via `oracle doctor --providers`, `--route`, and `--preflight` before spending API time.
- File safety: globs/excludes, size guards, `--files-report`.
- Sessions you can replay (`oracle status`, `oracle session --render`).
- Session logs and bundles live in `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
## API provider checks
Use these before expensive API or multi-model runs:
oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
oracle --preflight --models gpt-5.4,gemini-3-pro
oracle --provider openai --route --model gpt-5.4
`doctor` and `--preflight` print redacted readiness only: provider route, base host, key source, Azure state, and local configuration errors. `--route` shows the selected route and exits before creating a session. If Azure env/config is present but you want first-party OpenAI, add `--provider openai` or `--no-azure`.
For advisory panels where one good answer is useful, combine partial success with explicit output files:
oracle \
--models gpt-5.4,claude-4.6-sonnet,gemini-3-pro \
--allow-partial \
--write-output /tmp/oracle-panel.md \
-p "Compare these naming options"
Successful models write per-model files such as `/tmp/oracle-panel.gpt-5.4.md`; Oracle also writes `/tmp/oracle-panel.oracle.json` with successes, failures, output paths, and provider failure categories.
## Follow-up and lineage
Use `--followup` to continue a saved ChatGPT browser conversation or an existing OpenAI/Azure Responses API run with additional context/files:
oracle \
--followup \
--slug "my-browser-followup" \
-p "Follow-up: review this additional file in the same conversation." \
--file "server/src/strategy/plan.ts"
Browser followup reopens the exact saved conversation and inherits its browser profile, configuration, and model. Resume fails closed before submission if Oracle cannot verify the saved thread and prior turns.
oracle \
--engine api \
--model gpt-5.2-pro \
--followup \
--followup-model gpt-5.2-pro \
--slug "my-followup-run" \
--wait \
-p "Follow-up: re-evaluate the previous recommendation with the attached files." \
--file "server/src/strategy/plan.ts" \
--file "server/src/strategy/executor.ts"
When the parent session used `--models`, `--followup-model` picks which model's response id to chain from.
Custom `--base-url` providers plus Gemini/Claude API runs are excluded here because they do not preserve `previous_response_id` in Oracle.
`oracle status` shows parent/child lineage in tree form:
Recent Sessions
Status Model Mode Timestamp Chars Cost Slug
completed gpt-5.2-pro api 03/01/2026 09:00 AM 1800 $2.110 architecture-review-parent
completed gpt-5.2-pro api 03/01/2026 09:14 AM 2200 $2.980 ├─ architecture-review-followup
running gpt-5.2-pro api 03/01/2026 09:22 AM 1400 - │ └─ architecture-review-implementation-pass
pending gpt-5.2-pro api 03/01/2026 09:25 AM 900 - └─ architecture-review-risk-check
## Browser auto-reattach (long Pro runs)
When browser runs time out (common with long GPT‑5.x Pro responses), Oracle can keep polling the existing ChatGPT tab and capture the final answer without manual `oracle session ` commands.
Enable auto-reattach by setting a non-zero interval:
- `--browser-auto-reattach-delay` — wait before the first retry (e.g. `30s`)
- `--browser-auto-reattach-interval` — how often to retry (e.g. `2m`)
- `--browser-auto-reattach-timeout` — per-attempt budget (default `2m`)
oracle --engine browser \
--browser-timeout 6m \
--browser-auto-reattach-delay 30s \
--browser-auto-reattach-interval 2m \
--browser-auto-reattach-timeout 2m \
-p "Run the long UI audit" --file "src/**/*.ts"
## Calmer browser runs
Browser automation can open or control Chrome, so dry-runs and live runs print a short browser control plan before touching ChatGPT. Use it to choose the least disruptive path for shared desktops and agent-driven consults.
- `--dry-run summary --engine browser ...` previews whether Oracle will launch visible Chrome, hide a new window, attach to an existing browser, or use remote Chrome.
- `--browser-attach-running` and `--remote-chrome ` are the calmest options when a signed-in Chrome is already running with DevTools enabled.
- `--browser-hide-window` is best-effort: Chrome can briefly take focus before Oracle hides it.
- Long GPT-5.5 Pro browser consults are normal. Use `--heartbeat`, `oracle status`, and `oracle session ` instead of starting a duplicate run if the host agent appears to be waiting.
- Successful manual-profile runs close Oracle's own ChatGPT tab and clean up leftover blank startup tabs when no other Oracle browser slots are active. Incomplete runs leave the tab open so `oracle session ` can reattach.
## Flags you’ll actually use
| Flag | Purpose |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p, --prompt ` | Required prompt. |
| `-f, --file ` | Attach files/dirs (globs + `!` excludes). |
| `-e, --engine ` | Choose API or browser (browser is experimental). |
| `-m, --model ` | Built-ins (`gpt-5.5-pro` default, `gpt-5.5`, `gpt-5.4-pro`, `gpt-5.4`, `gpt-5.1-pro`, `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.2`, `gpt-5.2-instant`, `gpt-5.2-pro`, `gemini-3.1-pro` API + UI, `gemini-3-pro`, `claude-4.6-sonnet`, `claude-4.1-opus`) plus any OpenRouter id (e.g., `minimax/minimax-m2`, `openai/gpt-4o-mini`). |
| `--models
- ` | Comma-separated API models (mix built-ins and OpenRouter ids) for multi-model runs. |
| `--followup
标签：AI, ChatGPT, LLM, MITM代理, Promptflow, SOC Prime, Unmanaged PE, 代码助手, 开发工具, 暗色界面, 浏览器自动化, 自动化代码审查, 自动化攻击