oracle
Ask the oracle when you're stuck. Invoke GPT-5 Pro with a custom context and files.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/steipete/oracle with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/steipete/oracle'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/steipete--oracle)HTML
<a href="/listings/steipete--oracle"><img src="/api/listings/steipete--oracle/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
With Homebrew on macOS or Linux:
brew install steipete/tap/oracle
Or install the npm package globally:
npm install -g @steipete/oracle
Oracle requires Node.js 24 or newer. To try it without installing:
npx -y @steipete/oracle --help
See the [installation guide](docs/install.md) for pnpm, updates, API keys, and storage paths.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 136 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # oracle 🧿 — Bring a second brain, not a second briefing
- <p align="center">
- <img src="./README-header.png" alt="Oracle CLI header banner" width="1100">
- </p>
- <p align="center">
- <a href="https://github.com/steipete/oracle/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/steipete/oracle/ci.yml?branch=main&style=flat-square&label=ci" alt="CI status"></a>
- <a href="https://www.npmjs.com/package/@steipete/oracle"><img src="https://img.shields.io/npm/v/@steipete/oracle?style=flat-square" alt="npm version"></a>
- <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@steipete/oracle?style=flat-square" alt="Node.js version"></a>
- <a href="LICENSE"><img src="https://img.shields.io/github/license/steipete/oracle?style=flat-square" alt="License"></a>
- <a href="https://github.com/steipete/homebrew-tap/blob/main/Formula/oracle.rb"><img src="https://img.shields.io/badge/homebrew-steipete%2Ftap-orange?style=flat-square" alt="Homebrew tap"></a>
- </p>
- Oracle is a CLI and MCP server that bundles a prompt with the files you select, sends that context to an AI model through an API or a signed-in browser, and stores the result as a session. It is for developers and coding agents that need a second-model review grounded in the actual project.
- Full documentation is at [askoracle.sh](https://askoracle.sh).
- ## Install
- With Homebrew on macOS or Linux:
- ```bash
- brew install steipete/tap/oracle
- ```
- Or install the npm package globally:
- ```bash
- npm install -g @steipete/oracle
- ```
- Oracle requires Node.js 24 or newer. To try it without installing:
- ```bash
- npx -y @steipete/oracle --help
- ```
- See the [installation guide](docs/install.md) for pnpm, updates, API keys, and storage paths.
- ## Quick start
- Build a review bundle locally before connecting any model:
- ```bash
- oracle --render \
- -p "Review the package metadata for release risks" \
- --file package.json
- ```
- This prints the exact prompt and numbered file contents Oracle would send. It does not need credentials and does not contact a model.
- When an engine is configured, remove `--render` to request an answer:
- ```bash
- oracle \
- -p "Audit the model runner for race conditions" \
- --file "src/oracle/**/*.ts" \
- --file "!**/*.test.ts"
- ```
- Oracle chooses API mode when an OpenAI key is available and browser mode otherwise. Use `--engine api` or `--engine browser` to make the choice explicit. The [quickstart](docs/quickstart.md) covers the first API and browser runs.
- ## Choose an engine
- | Path | Use it when | Setup |
- | ------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
- | API | You want provider APIs, reliable automation, or multiple models in one run. | Set the key for the provider you use. |
- | Browser | You want Oracle to use a signed-in ChatGPT or Gemini browser session. | Install Chrome and complete the one-time login flow. |
- | Render | You want to inspect, copy, or paste the bundle yourself. | No account or key is required. |
- API mode supports OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, and compatible endpoints. Browser mode uses Chrome automation for ChatGPT and a cookie-based Gemini client. See [browser mode](docs/browser-mode.md) and [provider endpoints](docs/openai-endpoints.md) for setup and limits.
- ## Control the context
- `--file` accepts files, directories, globs, and `!` exclusions. Repeat it to compose the context you want reviewed. Preview the resolved files and token estimate before sending:
- ```bash
- oracle --dry-run summary --files-report \
- -p "Audit the model runner for race conditions" \
- --file "src/oracle/**/*.ts" \
- --file "!**/*.test.ts"
- ```
- Generated text bundles include stable line numbers so answers can cite `path:line`. In browser mode, one uploaded text/source file stays native and multiple text/source files are packed into one bundle: flattened text for text-only `auto` uploads, or a ZIP when raw files are present or `--browser-bundle-format zip` is set. Native images and documents remain direct attachments when possible. The [CLI reference](docs/cli-reference.md) lists the file, size, output, and browser controls.
- ## Sessions and follow-ups
- Oracle stores runs under `~/.oracle/sessions` so long responses can finish in the background and completed answers can be replayed. List recent work with:
- ```bash
- oracle status --hours 72
- ```
- Use `oracle session` to reattach to a run, `oracle restart` to repeat one, or `--followup` to continue a supported API or ChatGPT conversation with more context. See [sessions](docs/sessions.md) and [follow-ups](docs/followup.md) for the lifecycle and provider limits.
- ## Multiple models and automation
- `--models` runs an API panel and records per-model usage, cost, output, and partial failures in one session. `oracle doctor --providers` inspects readiness for the selected models without exposing credentials. The [multi-model guide](docs/multimodel.md) covers routing and output files.
- For agent integrations, run the `oracle-mcp` stdio server or install the Oracle skill from this repository. See [MCP setup](docs/mcp.md) and [agent setup](docs/agents.md) for Claude Code, Codex, Cursor, and other MCP clients.
- ## Documentation
- | Topic | Guide |
- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
- | Installation and first run | [Install](docs/install.md) · [Quickstart](docs/quickstart.md) |
- | Browser automation | [Browser mode](docs/browser-mode.md) · [Linux](docs/linux.md) · [Windows](docs/windows.md) |
- | Providers | [OpenAI and Azure](docs/openai-endpoints.md) · [Anthropic](docs/anthropic.md) · [Gemini](docs/gemini.md) · [OpenRouter](docs/openrouter.md) |
- | Runs and models | [Sessions](docs/sessions.md) · [Follow-ups](docs/followup.md) · [Multi-model](docs/multimodel.md) |
- | Configuration and commands | [Configuration](docs/configuration.md) · [CLI reference](docs/cli-reference.md) |
- | Agent integrations | [Agents](docs/agents.md) · [MCP](docs/mcp.md) · [Bridge](docs/bridge.md) |
- ## Related projects
- - [Trimmy](https://trimmy.app) — Flatten multiline shell snippets so they paste and run once.
- - [CodexBar](https://codexbar.app) — Keep Codex token windows visible in the macOS menu bar.
- - [MCPorter](https://mcporter.dev) — TypeScript toolkit and CLI for Model Context Protocol servers.
- The name was inspired by [Amp's Oracle](https://ampcode.com/news/oracle).
- ## Development
- ```bash
- pnpm install
- pnpm check
- pnpm test
- pnpm build
- pnpm docs:check
- ```
- Manual browser and provider tests are documented in [docs/manual-tests.md](docs/manual-tests.md).
- ## License
- MIT. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.