Oracle AI Agent

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

<p align="center"> <img src="./README-header.png" alt="Oracle CLI header banner" width="1100"> </p> <p align="center"> <a href="https://github.com/steipete/oracle/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/steipete/oracle/ci.yml?branch=main&style=flat-square&label=ci" alt="CI status"></a> <a href="https://www.npmjs.com/package/@steipete/oracle"><img src="https://img.shields.io/npm/v/@steipete/oracle?style=flat-square" alt="npm version"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@steipete/oracle?style=flat-square" alt="Node.js version"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/steipete/oracle?style=flat-square" alt="License"></a> <a href="https://github.com/steipete/homebrew-tap/blob/main/Formula/oracle.rb"><img src="https://img.shields.io/badge/homebrew-steipete%2Ftap-orange?style=flat-square" alt="Homebrew tap"></a> </p>

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.

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.