oracle README

The project's README from github.com/steipete/oracle. As one markdown file: README.md.

oracle 🧿 — Bring a second brain, not a second briefing

Oracle CLI header banner

CI status npm version Node.js version License Homebrew tap

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.

Install

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 for pnpm, updates, API keys, and storage paths.

Quick start

Build a review bundle locally before connecting any model:

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:

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 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 and provider endpoints 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:

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 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:

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 and follow-ups 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 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 and agent setup for Claude Code, Codex, Cursor, and other MCP clients.

Documentation

Topic Guide
Installation and first run Install · Quickstart
Browser automation Browser mode · Linux · Windows
Providers OpenAI and Azure · Anthropic · Gemini · OpenRouter
Runs and models Sessions · Follow-ups · Multi-model
Configuration and commands Configuration · CLI reference
Agent integrations Agents · MCP · Bridge

The name was inspired by Amp's Oracle.

Development

pnpm install
pnpm check
pnpm test
pnpm build
pnpm docs:check

Manual browser and provider tests are documented in docs/manual-tests.md.

License

MIT. See LICENSE.

oracle (steipete/oracle)

Searching Database…

4.1K ·GitHub
Oracle
What is this?Oracle is a CLI and MCP server that bundles a prompt with files you select, sends that context to an AI model via an API or a signed-in browser session, and stores the result as a replayable session.
Is this a CLI tool, or does it run as a server?It works as a standalone CLI command (`oracle`) and also as an MCP (Model Context Protocol) server (`oracle-mcp`), so coding agents like Claude Code, Codex, and Cursor can call it directly.
How do I install and run it?Install with Homebrew on macOS or Linux, or install the npm package globally; Node.js 24 or newer is required. You can also try it without installing first.
Do I need an API key, or can I use my browser login instead?API mode needs a key for OpenAI, Azure OpenAI, Anthropic, Gemini, xAI, OpenRouter, or a compatible endpoint; browser mode instead uses a signed-in ChatGPT or Gemini session through Chrome, no key required.
Can I try it without setting up any credentials first?Yes — running with `--render` builds and prints the exact prompt and file bundle Oracle would send, without contacting any model or needing credentials, so you can inspect it before committing to an engine.
Does it run on Windows, or just macOS and Linux?Homebrew installation targets macOS and Linux, but Oracle is also distributed as an npm package and has dedicated browser-mode setup docs for Windows.
Can Oracle query more than one model at once?Yes, the --models flag runs an API panel across multiple models in one session and records per-model usage, cost, output, and partial failures.
How does Oracle decide what files to send?You pass --file with files, directories, or globs (with ! exclusions); it can preview the resolved file list and a token estimate before sending anything to a model.
Why is it called Oracle?The author says the name was inspired by Amp's Oracle feature, reflecting the idea of consulting a second model for a grounded review.
Are there related tools from the same author?Yes — Trimmy for flattening shell snippets, CodexBar for showing Codex token windows in the macOS menu bar, and MCPorter, a TypeScript toolkit/CLI for MCP servers.
What are similar projects?headroom, billion-context, copperhead, jevmem, bb-browser, claude-task-master, rea, claude-code
Which topics is it in?gemini-pro, browser-automation, model-context-protocol, cursor, anthropic, agents, mcp-server, coding-agent, openai, codex, command-line-tool, claude-code
Creator
steipete
Size
88.6 MB
Stars
4.1K
Updated
CommitOct 16Releasev0.21.6Oct 16
Age
11mo
Commits · 90 Days