TopGit
GitHub Repo Review

Oracle AI CLI: Bundle Code Context for AI Review

steipete/oracle
OTopGit review image for steipete/oracle
Review by Topgit.dev for steipete/oracle, with GitHub repository stats and README context.
Quick verdict

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.

Stars
โ˜… 4.1k
Forks
โ‘‚ 434
Contributors
๐Ÿ‘ฅ 73
Language
TypeScript
License
MIT
Topic
AI Tools
Updated
Nov 2026

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.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history โ†—

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

What AI models and providers does Oracle support?

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.

What are the installation requirements for Oracle?

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.

How does Oracle handle context for AI models?

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.

Can Oracle be used with a web browser for AI interactions?

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.

What is the license for Oracle?

Oracle is released under the MIT license, per its GitHub repository.

How does Oracle manage AI conversation sessions and follow-ups?

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

Source & attribution

Facts and quotes sourced from the steipete/oracle GitHub repository and its README.

GitHub data ยท last synced Aug 12, 2026Reviewed by Henry
โ† Back to TopGit

Want a second opinion on oracle?

Ask an AI that can read this page โ€” one click and you get its take on oracle.

GitHub