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
这是什么？Oracle 是一个 CLI 和 MCP 服务器，把你选择的文件与提示词打包，通过 API 或已登录的浏览器会话把这份上下文发送给 AI 模型，并将结果存储为可回放的会话。
这是 CLI 工具，还是作为服务器运行？它既可以作为独立的 CLI 命令（`oracle`）运行，也可以作为 MCP（Model Context Protocol）服务器（`oracle-mcp`）运行，因此 Claude Code、Codex 和 Cursor 等编程代理可以直接调用它。
怎么安装和运行它？在 macOS 或 Linux 上用 Homebrew 安装，或全局安装 npm 包；需要 Node.js 24 或更新版本。你也可以在安装前先试用。
我需要 API 密钥，还是可以用浏览器登录代替？API 模式需要 OpenAI、Azure OpenAI、Anthropic、Gemini、xAI、OpenRouter 或兼容端点的密钥；浏览器模式则通过 Chrome 使用已登录的 ChatGPT 或 Gemini 会话，无需密钥。
能在不先配置任何凭证的情况下试用吗？可以——用 `--render` 运行会构建并打印 Oracle 将要发送的确切提示词和文件包，不接触任何模型也不需要凭证，你可以在选定引擎之前先检查内容。
它能在 Windows 上运行，还是只有 macOS 和 Linux？Homebrew 安装面向 macOS 和 Linux，但 Oracle 也以 npm 包的形式分发，并且有专门针对 Windows 的浏览器模式设置文档。
Oracle 能同时查询多个模型吗？可以，--models 标志可在一次会话中跨多个模型运行 API 横评，并记录每个模型的用量、成本、输出和部分失败情况。
Oracle 如何决定发送哪些文件？你用 --file 传入文件、目录或通配符模式（支持 ! 排除）；在向模型发送任何内容之前，它可以预览解析出的文件列表和 token 估算。
为什么叫 Oracle？作者说这个名字的灵感来自 Amp 的 Oracle 功能，体现了让第二个模型做扎实审查的思路。
同一作者还有其他相关工具吗？有——用于扁平化 shell 片段的 Trimmy、在 macOS 菜单栏显示 Codex token 窗口的 CodexBar，以及面向 MCP 服务器的 TypeScript 工具包/CLI MCPorter。
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.8 MB
Stars
4.1K
Updated
CommitOct 17Releasev0.21.6Oct 16
Age
11mo
Commits · 90 Days