Skip to content
Back to search

oracle

Ask the oracle when you're stuck. Invoke GPT-5 Pro with a custom context and files.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/steipete/oracle with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/steipete/oracle'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/steipete--oracle/badge.svg)](/listings/steipete--oracle)

HTML

<a href="/listings/steipete--oracle"><img src="/api/listings/steipete--oracle/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](docs/install.md) for pnpm, updates, API keys, and storage paths.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 136 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # oracle 🧿 — Bring a second brain, not a second briefing
  2. <p align="center">
  3. <img src="./README-header.png" alt="Oracle CLI header banner" width="1100">
  4. </p>
  5. <p align="center">
  6. <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>
  7. <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>
  8. <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@steipete/oracle?style=flat-square" alt="Node.js version"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/github/license/steipete/oracle?style=flat-square" alt="License"></a>
  10. <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>
  11. </p>
  12. 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.
  13. Full documentation is at [askoracle.sh](https://askoracle.sh).
  14. ## Install
  15. With Homebrew on macOS or Linux:
  16. ```bash
  17. brew install steipete/tap/oracle
  18. ```
  19. Or install the npm package globally:
  20. ```bash
  21. npm install -g @steipete/oracle
  22. ```
  23. Oracle requires Node.js 24 or newer. To try it without installing:
  24. ```bash
  25. npx -y @steipete/oracle --help
  26. ```
  27. See the [installation guide](docs/install.md) for pnpm, updates, API keys, and storage paths.
  28. ## Quick start
  29. Build a review bundle locally before connecting any model:
  30. ```bash
  31. oracle --render \
  32. -p "Review the package metadata for release risks" \
  33. --file package.json
  34. ```
  35. This prints the exact prompt and numbered file contents Oracle would send. It does not need credentials and does not contact a model.
  36. When an engine is configured, remove `--render` to request an answer:
  37. ```bash
  38. oracle \
  39. -p "Audit the model runner for race conditions" \
  40. --file "src/oracle/**/*.ts" \
  41. --file "!**/*.test.ts"
  42. ```
  43. 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](docs/quickstart.md) covers the first API and browser runs.
  44. ## Choose an engine
  45. | Path | Use it when | Setup |
  46. | ------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
  47. | API | You want provider APIs, reliable automation, or multiple models in one run. | Set the key for the provider you use. |
  48. | Browser | You want Oracle to use a signed-in ChatGPT or Gemini browser session. | Install Chrome and complete the one-time login flow. |
  49. | Render | You want to inspect, copy, or paste the bundle yourself. | No account or key is required. |
  50. 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](docs/browser-mode.md) and [provider endpoints](docs/openai-endpoints.md) for setup and limits.
  51. ## Control the context
  52. `--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:
  53. ```bash
  54. oracle --dry-run summary --files-report \
  55. -p "Audit the model runner for race conditions" \
  56. --file "src/oracle/**/*.ts" \
  57. --file "!**/*.test.ts"
  58. ```
  59. 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](docs/cli-reference.md) lists the file, size, output, and browser controls.
  60. ## Sessions and follow-ups
  61. Oracle stores runs under `~/.oracle/sessions` so long responses can finish in the background and completed answers can be replayed. List recent work with:
  62. ```bash
  63. oracle status --hours 72
  64. ```
  65. 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](docs/sessions.md) and [follow-ups](docs/followup.md) for the lifecycle and provider limits.
  66. ## Multiple models and automation
  67. `--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](docs/multimodel.md) covers routing and output files.
  68. For agent integrations, run the `oracle-mcp` stdio server or install the Oracle skill from this repository. See [MCP setup](docs/mcp.md) and [agent setup](docs/agents.md) for Claude Code, Codex, Cursor, and other MCP clients.
  69. ## Documentation
  70. | Topic | Guide |
  71. | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
  72. | Installation and first run | [Install](docs/install.md) · [Quickstart](docs/quickstart.md) |
  73. | Browser automation | [Browser mode](docs/browser-mode.md) · [Linux](docs/linux.md) · [Windows](docs/windows.md) |
  74. | Providers | [OpenAI and Azure](docs/openai-endpoints.md) · [Anthropic](docs/anthropic.md) · [Gemini](docs/gemini.md) · [OpenRouter](docs/openrouter.md) |
  75. | Runs and models | [Sessions](docs/sessions.md) · [Follow-ups](docs/followup.md) · [Multi-model](docs/multimodel.md) |
  76. | Configuration and commands | [Configuration](docs/configuration.md) · [CLI reference](docs/cli-reference.md) |
  77. | Agent integrations | [Agents](docs/agents.md) · [MCP](docs/mcp.md) · [Bridge](docs/bridge.md) |
  78. ## Related projects
  79. - [Trimmy](https://trimmy.app) — Flatten multiline shell snippets so they paste and run once.
  80. - [CodexBar](https://codexbar.app) — Keep Codex token windows visible in the macOS menu bar.
  81. - [MCPorter](https://mcporter.dev) — TypeScript toolkit and CLI for Model Context Protocol servers.
  82. The name was inspired by [Amp's Oracle](https://ampcode.com/news/oracle).
  83. ## Development
  84. ```bash
  85. pnpm install
  86. pnpm check
  87. pnpm test
  88. pnpm build
  89. pnpm docs:check
  90. ```
  91. Manual browser and provider tests are documented in [docs/manual-tests.md](docs/manual-tests.md).
  92. ## License
  93. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.