steipete/oracle: a CLI and MCP server for second-model code review

The gap Oracle fills between a chat window and a real repository

Pasting code into a chat window loses two things: which files you left out, and where each line came from. Oracle's answer is to make the bundle a first-class artifact. The README describes the project as a CLI and MCP server that bundles a prompt with selected files, sends that context to a model, and stores the result as a session. It is aimed at developers and coding agents that need a second-model review grounded in the actual project.

The audience is narrower than "anyone who uses AI." If you want a general assistant, a browser tab is cheaper. Oracle earns its place when the input is a set of files you chose deliberately, when the answer needs to point back at a specific line, and when you want the run recorded so you can reattach or repeat it. The README's own framing, "bring a second brain, not a second briefing," points at the same idea: the value is in the context you hand over, not in the wrapper around the model call.

One structural detail matters for how you read the rest of the documentation. The package description in package.json calls it a "CLI wrapper around OpenAI Responses API," while the README lists API support for OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, and compatible endpoints. The package metadata lags the documented provider list.

How the bundle, the engine choice, and the session store fit together

The data flow has three stages. First, Oracle resolves your --file arguments into a concrete file list, including globs and ! exclusions, and estimates token count. Second, it renders that list into a prompt bundle with stable line numbers. Third, it sends the bundle through one of three paths and writes the run to disk.

Engine selection is automatic by default. The README states that Oracle chooses API mode when an OpenAI key is available and browser mode otherwise, and that --engine api or --engine browser makes the choice explicit. Browser mode is not a fallback toy: it drives Chrome for ChatGPT and uses a cookie-based client for Gemini, which means the model traffic rides on a signed-in session instead of a metered key.

The upload shape differs by mode, and this is the part most likely to surprise you. In browser mode, the README says one uploaded text or source file stays native, while multiple text or source files are packed into one bundle: flattened text for text-only auto uploads, or a ZIP when raw files are present or when --browser-bundle-format zip is set. Native images and documents remain direct attachments where possible. So the same command can produce a flattened prompt or a ZIP depending on what you included and which flag you passed.

Sessions live under ~/.oracle/sessions. The README gives two reasons: long responses can finish in the background, and completed answers can be replayed. That store is also what makes oracle session, oracle restart, and --followup possible, though the README defers the lifecycle and provider limits to docs/sessions.md and docs/followup.md.

Installing Oracle and running a first review bundle

Oracle requires Node.js 24 or newer. On macOS or Linux, the README gives a Homebrew formula, and the npm package is published as @steipete/oracle.

brew install steipete/tap/oracle

The npm route installs the same CLI globally, and the README also offers a no-install check through npx.

npm install -g @steipete/oracle
npx -y @steipete/oracle --help

The first useful command needs no credentials at all. --render prints the exact prompt and numbered file contents Oracle would send, which lets you inspect the bundle before any model is involved. The README uses a package metadata review as the example.

oracle --render \
  -p "Review the package metadata for release risks" \
  --file package.json

What you should see is the prompt text followed by the file contents with line numbers. If the file list is wrong, fix it here, not after you have paid for a run.

When you want an actual answer, drop --render and widen the file set. The README's example audits a source tree while excluding tests, using a repeated --file flag and a ! exclusion.

oracle \
  -p "Audit the model runner for race conditions" \
  --file "src/oracle/**/*.ts" \
  --file "!**/*.test.ts"

Before sending something large, the README suggests a dry run that reports the resolved files and a token estimate. This is the command to reach for when a bundle feels bigger than it should be.

oracle --dry-run summary --files-report \
  -p "Audit the model runner for race conditions" \
  --file "src/oracle/**/*.ts" \
  --file "!**/*.test.ts"

After a run, oracle status --hours 72 lists recent work, and oracle doctor --providers checks readiness for selected models without exposing credentials.

Where Oracle stops being the right tool

Browser mode is the sharpest limitation. It depends on Chrome automation for ChatGPT and a cookie-based Gemini client, so it inherits whatever the browser session does. The README points to docs/browser-mode.md and docs/linux.md and docs/windows.md for setup and limits, which is a signal that the platform-specific behaviour is not something the top-level README tries to summarize. If your environment has no Chrome, or your organisation treats browser automation of a signed-in account as out of bounds, API mode is the only path left, and that means a provider key.

The second constraint is context size. Oracle gives you the tools to see the cost (--dry-run with --files-report, --render) but it does not decide what belongs in the bundle. A glob like src/oracle/**/*.ts with an exclusion for tests is a judgement call, and an over-broad one produces a large, expensive, noisy request. The README documents the size controls in docs/cli-reference.md rather than inline, so you will be reading that page before your first serious run.

Third, follow-ups are not universal. The README says --followup continues a supported API or ChatGPT conversation, and defers provider limits to docs/followup.md. "Supported" is doing real work in that sentence: do not assume every provider in the API list can be resumed.

Finally, Oracle is not a code search tool, a linter, or a test runner. It sends text to a model. If your question can be answered by running the code, run the code.

Oracle versus a single-vendor review product

The obvious alternative is a hosted code review product tied to one model vendor, where you install a GitHub app, the service selects the diff, and the review arrives as a comment. The difference is who owns context selection. A hosted reviewer decides what the model sees, usually a diff plus repository retrieval. Oracle hands that decision to you: --file takes files, directories, globs, and ! exclusions, and you repeat the flag to compose exactly the set you want reviewed. That is more work and more control.

The second difference is engine plurality. Oracle's API mode supports OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, and compatible endpoints, and --models runs an API panel that records per-model usage, cost, output, and partial failures in one session. A single-vendor product cannot ask two vendors the same question in one run. Oracle can, and the README says the panel writes per-model results into one session rather than scattering them.

The third difference is the render path. --render produces the bundle without contacting a model or needing credentials. That makes Oracle usable as a bundle builder even if you paste the result into a different tool entirely. A hosted reviewer has no equivalent: the context never leaves the service.

The trade-off is operational. Hosted reviewers run on their infrastructure with their keys. Oracle runs on your machine, needs Node.js 24 or newer, and in API mode needs your provider key or, in browser mode, a Chrome session you have logged into.

Maintenance, licensing, and what upgrades cost you

Oracle is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive, so the practical implication is that you can use and modify the code with few obligations, but you should read the licence text yourself rather than take a summary as legal advice. The repository is not archived, and the last push was on 2026-09-14, the same day as the v0.20.3 release. Releases v0.20.1 through v0.20.3 landed within three days of each other, so the version line moves quickly.

That pace is the real upgrade cost. Anything pinned to a specific behaviour, especially browser mode's upload packing and the session format under ~/.oracle/sessions, is worth re-checking after a version bump. The README documents the storage path but not a migration story for it, so if you script against session files rather than the CLI, you are depending on an undocumented shape.

Installation is the cheap part. Homebrew and npm both work, and pnpm is covered in docs/install.md, which the README also says covers updates, API keys, and storage paths. The expensive part is the model traffic itself, which is why --dry-run and --render exist.

For agent integrations, the repository ships a skills/ directory and the npm package exposes a second binary, oracle-mcp, alongside oracle. The README points at docs/mcp.md and docs/agents.md for Claude Code, Codex, Cursor, and other MCP clients.

Editorial conclusion

Adopt Oracle if you already pay for a provider API or have a signed-in ChatGPT or Gemini session and you want review answers that cite path:line against real files. Skip it if you need a self-hosted model with no external API, or if you want a single vendor's paid product to handle context selection for you. Before relying on it, run oracle --render on one small bundle and check that the resolved file list and token estimate match what you intended to send, because the file selection is the part you own.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. steipete/oracle on GitHub