oracle: a CLI that bundles your files into a second-model review

What oracle is for, and who ends up using it

A coding agent reviewing its own work has a structural problem: the same model that wrote the code decides whether the code is good. oracle exists to break that loop. The README describes it as a CLI and MCP server that bundles a prompt with 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. The stated audience is developers and coding agents that need a second-model review grounded in the actual project.

The operative phrase is grounded in the actual project. You are not describing your architecture to a chat window and hoping the paraphrase is faithful. You pass globs, oracle resolves them to real files, numbers the lines, and sends that. Answers can then cite path:line, which is the difference between a review you can act on and a review you have to re-verify before you trust it.

The second audience is agents themselves. The package publishes two binaries, oracle and oracle-mcp, and the repository ships a skills/ directory plus documentation for Claude Code, Codex and Cursor. So the same bundle you build by hand can be exposed as a tool an agent calls mid-task. That is the more interesting use, and it is also the one with the most setup friction.

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

Three modes share one context-building path. Render mode prints the prompt and numbered file contents without credentials and without contacting a model. API mode sends the bundle to a provider endpoint. Browser mode drives Chrome against a signed-in ChatGPT session, or uses a cookie-based Gemini client.

Selection is done with --file, which accepts files, directories, globs and ! exclusions, and can be repeated. Resolution happens before any network call, which is why --dry-run summary --files-report can show the resolved file list and a token estimate first. That ordering matters: the expensive mistake in this class of tool is discovering after the fact that a glob pulled in a lockfile or a test fixture and inflated the request.

Engine selection is implicit 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. Implicit selection is convenient and slightly hazardous: a stray OPENAI_API_KEY in your shell silently changes which path runs, and with it whether your code goes to an API or into a browser session.

Runs are stored under ~/.oracle/sessions. Long responses can finish in the background, completed answers can be replayed, and --followup continues a supported API or ChatGPT conversation with more context. --models runs an API panel across several models and records per-model usage, cost, output and partial failures in one session. Partial failure being a first-class recorded outcome is the honest design choice here; a panel where one provider times out should not read as a clean result.

Installing oracle and running a review without credentials

The README gives two install paths. Homebrew on macOS or Linux, or a global npm install. Oracle requires Node.js 24 or newer, which is a hard floor rather than a suggestion.

brew install steipete/tap/oracle

npm install -g @steipete/oracle

If you only want to see the CLI before committing to an install, the README offers a no-install run of the help output:

npx -y @steipete/oracle --help

The safest first real use needs no account and no key. Render mode builds the bundle locally and prints exactly what would be sent:

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

The expected output is the prompt followed by the numbered contents of package.json. Nothing leaves the machine. Once an engine is configured, drop --render to actually request an answer, and use the dry run to check scope before spending tokens:

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

From there, oracle status --hours 72 lists recent runs, oracle session reattaches to one, and oracle restart repeats it.

Where the context controls get awkward

Browser mode is the part of the design with visible seams, and the README is candid about them. One uploaded text or source file stays native. Multiple text or source files get 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.

That is a compatibility layer over a chat interface that was not designed to receive a repository. The consequence is that line-number citations in browser mode depend on how the bundle was assembled, and a flattened auto upload is a different artifact from a ZIP. If you care about path:line references surviving into the answer, the upload format is not a detail you can ignore.

There is a second constraint the README states plainly: browser mode needs Chrome installed and a one-time login flow completed. That makes it a poor fit for headless CI, where API mode is the only path that does not require a human to have signed in. API mode in turn supports OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter and compatible endpoints, so the trade is not browser versus nothing; it is browser versus a key and a bill.

Finally, follow-ups are provider-limited. The README says --followup continues a supported API or ChatGPT conversation, and points to a follow-up guide for the lifecycle and provider limits. The word supported is doing real work there. Do not assume every model in a panel can be continued.

oracle against asking ChatGPT or Claude directly

The obvious alternative is pasting files into a chat window yourself. The difference is not the model. It is who resolves the context and whether the run is reproducible.

With a hand-pasted prompt, you decide what fits in the window, you lose line numbers unless you add them, and the next person who wants the same review reconstructs it from memory. With oracle, the selection is an argument list. oracle --render -p "..." --file package.json is a command someone else can run and get the same bundle. That reproducibility is the actual product.

A closer alternative is a code review tool that runs a model over a diff inside your CI pipeline. Those are built around pull requests and post comments; oracle is built around sessions you invoke and reattach to, with a session store under ~/.oracle/sessions. If your review process is comment-on-PR, oracle is the wrong shape. If your process is a developer or an agent wanting a second opinion on a slice of the tree, with the option to follow up, oracle matches it better.

There is also the multi-model angle. --models runs a panel and records per-model usage, cost, output and partial failures in one session. Doing that by hand across four provider dashboards is tedious enough that most people do not bother.

Maintenance, upgrades and the MIT licence

The repository is not archived and the last push was on 2026-09-14. Releases are frequent: v0.20.3 landed on 2026-09-14, v0.20.2 on 2026-09-12 and v0.20.1 on 2026-09-12. A version still in the 0.x range with that release cadence means the interface can move, so pin the version you install and read the changelog before upgrading rather than tracking latest.

The Node.js 24 or newer requirement is the upgrade cost that will bite first. If your toolchain is on an older LTS line, oracle is not installable until you move, and that is a decision about your whole environment, not about this tool.

The package is MIT licensed, which is permissive and places few obligations on how you use or redistribute it. That licence covers the code in the repository. It does not cover the model providers you call through it: your OpenAI, Anthropic, Gemini, xAI or OpenRouter terms, and your data handling obligations for whatever file contents you send, are separate agreements you already have or need. Nothing here is legal advice, and the licence file is the authority on the licence.

Editorial conclusion

Adopt oracle if you already pay for an OpenAI, Anthropic, Gemini or OpenRouter key and want file-grounded second opinions that can be replayed, or if you drive Claude Code, Codex or Cursor and want the same review available as an MCP tool. Skip it if your code cannot leave your machine, since API mode sends file contents to a provider and browser mode drives a signed-in Chrome session, or if you need a review process that runs inside CI without a human login. Verify first that Node.js 24 or newer is available, run oracle --render on the exact glob set you intend to use to confirm which files and how many tokens would be sent, and run oracle doctor --providers to confirm the keys for the models you plan to call before you rely on a panel run.

Frequently asked questions

Official sources

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