Oracle AI CLI: Bundle Code Context for AI Review
Functioning as both a CLI and an MCP server, Oracle gathers a prompt along with selected files and then sends this to an AI model using either a provider API or a browser where the user is signed in, with the conversation saved as a session on disk. It reaches OpenAI, Anthropic, Gemini, xAI, Azure OpenAI, and OpenRouter in API mode, plus ChatGPT and Gemini via browser automation. Reach for it for a real code review grounded in actual files; skip it if a plain chat window already does the job.
What Oracle Is
Oracle is a CLI and MCP server for packaging code context and sending it to a large language model for review. It bundles a prompt with the files, directories, or globs you select, routes that bundle through a provider API or a signed-in browser, and saves the response under ~/.oracle/sessions for later replay. It's built for developers and coding agents wanting a second opinion grounded in the real project, not a pasted description of it.
Installation Guide
On macOS or Linux, Homebrew installs Oracle with brew install steipete/tap/oracle. Anywhere Node.js runs, npm install -g @steipete/oracle sets up the global CLI โ but Oracle needs Node 24 or newer to run at all. To try it without installing anything, npx -y @steipete/oracle --help pulls it down once and prints the help output. A separate install guide in the repo (docs/install.md) covers the pnpm path, updates, API key setup, and storage paths in more depth than the top-level README does.
Getting Started and Context Control
A first run typically starts with --render, e.g. oracle --render -p "Review the package metadata for release risks" --file package.json, which prints the exact prompt and numbered file contents without touching credentials or reaching a model. Drop --render once a provider is configured and the same shape of command sends the bundle and returns an answer โ --file takes individual files, whole directories, glob patterns like src/oracle/**/*.ts, or a !-prefixed exclusion such as !**/*.test.ts, and you can repeat the flag to compose exactly the context you want reviewed. Left alone, Oracle picks API mode when it finds an OpenAI key and falls back to browser mode otherwise; --engine api or --engine browser overrides that choice. Before spending a request, --dry-run summary --files-report lists which files resolved and estimates the token count. Every generated bundle numbers its lines, which is what lets an answer cite an exact path:line instead of a vague reference.
Core Capabilities
- โThree engines to choose from: API mode for scriptable runs once a provider key is set, browser mode for riding an already-signed-in ChatGPT or Gemini session after a one-time Chrome login, and render mode, which needs no account or key because nothing leaves your machine.
- โAPI mode reaches OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, and other OpenAI-compatible endpoints.
- โ--file composes context from individual files, whole directories, glob patterns, and !-prefixed exclusions, repeatable across a single command.
- โGenerated text bundles carry stable line numbers, so a model's answer can point back to an exact path:line.
- โRuns are stored under ~/.oracle/sessions; a slow response keeps generating in the background instead of blocking your terminal, and oracle status --hours 72 lists what ran recently.
- โ--followup continues an existing API or ChatGPT conversation with more context instead of starting a new one from scratch.
- โ--models fires one prompt at several models in a single run and logs each model's usage, cost, output, and any partial failure together.
- โAn oracle-mcp stdio server, plus an installable Oracle skill, let MCP clients like Claude Code, Codex, and Cursor call Oracle directly as a tool.
Practical Developer Applications
- โขScoping a focused AI code review to a slice of the codebase, e.g. --file "src/oracle/**/*.ts" --file "!**/*.test.ts", and getting an answer that cites specific files and lines.
- โขChecking what would actually get sent before spending a request or exposing files, using --render or --dry-run summary --files-report to preview the bundle and token estimate.
- โขRunning the same question across multiple providers at once with --models to compare cost, output, and failures side by side โ useful when you don't trust a single model's read.
- โขWiring Oracle into an agent's own toolset through the oracle-mcp stdio server so a coding agent, not just a human, can request a grounded second opinion mid-task.
- โขResuming or repeating a long-running review later with oracle session, oracle restart, or --followup instead of re-sending the whole context again.
Who Is Oracle For?
Oracle fits developers who already juggle more than one model provider and want one CLI that can hand the same file-grounded context to any of them, plus coding agents that need to call out for a second opinion mid-task through MCP. It also suits anyone who wants to inspect exactly what gets sent before it's sent, since render mode needs no key or account at all. Skip it if you only ever ask one model one-off questions in a browser tab โ the session storage, multi-model panel, and MCP wiring are overhead you won't use.
Strengths
- โ--render shows the exact prompt and file bundle with zero credentials before anything reaches a model โ useful for trust and for controlling what leaves your machine.
- โReal multi-provider reach in API mode: OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, and compatible endpoints, per the README.
- โSession storage under ~/.oracle/sessions means a slow response keeps generating in the background instead of blocking your terminal, and you can reattach later.
- โ--models runs a genuine multi-model comparison in one call, logging usage, cost, output, and partial failures together instead of forcing separate runs.
- โMCP support (oracle-mcp, an installable skill) makes Oracle something a coding agent can call directly, not only a tool a human runs by hand.
- โMIT license, no proprietary strings attached.
Considerations and Constraints
- โณThe top-level README defers a lot of detail to separate docs (install, quickstart, browser mode, CLI reference, and more) rather than documenting updates, storage paths, or the full flag set inline.
- โณBrowser mode isn't zero-setup: it needs Chrome installed and a one-time signed-in login before ChatGPT or Gemini access through it will work.
- โณAPI mode is cloud-provider-only in the facts available โ OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, and compatible endpoints are listed, with nothing about local or self-hosted models.
- โณInstalling via npm requires Node.js 24 or newer, which rules out older Node setups without switching versions first.
- โณNo version number, release date, or changelog appears in the facts available, so there's no documented way to gauge how mature or fast-moving a given release is.
Alternative and Related Projects
Common Questions
Oracle's API mode reaches OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, and OpenRouter plus other compatible endpoints, and its browser mode can drive ChatGPT and Gemini through a signed-in session instead.
Oracle needs Node.js 24 or newer. Install it with Homebrew (steipete/tap/oracle) on macOS or Linux, install the @steipete/oracle npm package globally, or try it once with npx -y @steipete/oracle --help before committing to install.
Oracle builds context with --file, which accepts individual files, directories, globs, and !-prefixed exclusions repeated across a command, then numbers every line of the resulting bundle so answers can cite an exact path:line.
Oracle's browser mode drives a signed-in Chrome session to reach ChatGPT and uses a cookie-based client for Gemini, as an alternative to going through a provider API.
Oracle is released under the MIT license, per its GitHub repository.
Oracle stores every run under ~/.oracle/sessions so slow responses keep working in the background; oracle status lists recent runs, oracle session reattaches to one, oracle restart repeats it, and --followup continues a supported API or ChatGPT conversation with more context.
The problem it solves
Getting a second model's opinion on code usually means copying files into a chat window by hand, losing line numbers, and starting over each time you want to revisit the answer. Oracle's own GitHub tagline frames the gap bluntly: call up a model like GPT-5 Pro with a hand-picked context and file set instead. The README builds on that by keeping the exchange as a saved session tied to real files sent through an actual API or browser, rather than a one-off copy-paste.
Related repositories
Curious whether oracle is right for you?
Let ChatGPT, Claude, or Perplexity look into it โ click below and see what AI actually says about oracle.
