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

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 |

Related projects

• Trimmy — Flatten multiline shell snippets so they paste and run once.
• CodexBar — Keep Codex token windows visible in the macOS menu bar.
• MCPorter — TypeScript toolkit and CLI for Model Context Protocol servers.

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.