Oracle instantly bundles your prompt with relevant files and queries GPT-5.4 Pro or other frontier models, delivering precise, context-aware breakthroughs exactly when you feel stuck.
What Is Oracle and Why It Matters for Modern Development
Oracle, created by steipete and available at https://github.com/steipete/oracle, is a lightweight, open-source command-line tool that solves one of the most persistent frustrations in AI-assisted development: context loss. Instead of manually copying files into ChatGPT, Gemini, or Claude and watching token limits evaporate, Oracle assembles a clean Markdown bundle from your prompt and any files or directories you specify, then forwards it to the most capable models available today.
Released with rapid iteration in early 2026, Oracle now powers over 1,600 GitHub stars and continues receiving updates as recently as March 2026. It supports both API-driven execution (using your existing keys for OpenAI, Gemini, Anthropic, Azure, or OpenRouter) and experimental browser automation that requires no API keys at all on macOS. The result is a frictionless experience that feels like whispering directly to a silicon sage.
In an era where frontier models such as GPT-5.4 Pro can reason across hundreds of thousands of tokens, the bottleneck is no longer raw intelligence—it is delivering the right context efficiently. Oracle removes that bottleneck, enabling developers to debug complex issues, perform architecture reviews, generate documentation, or validate assumptions without breaking flow.
The Power of Intelligent Context Bundling
At its core, Oracle excels at selective context assembly. You provide a prompt and file patterns using glob syntax, and Oracle intelligently includes only the requested content while respecting size guards and token estimates. Excludes are supported with the familiar ! prefix, and a --files-report flag shows exactly what will be sent before any cost is incurred.
The bundled output is formatted as clean Markdown optimized for frontier models. This approach preserves file structure, code syntax, and comments far better than copy-paste workflows. Dry-run mode lets you preview the exact bundle and token count without spending a single credit, giving confidence before committing resources.
Beyond one-shot queries, Oracle preserves session lineage. Every run receives a unique identifier and is stored locally in ~/.oracle/sessions. Follow-up commands can reference a previous session ID or specific response ID, allowing iterative refinement across multiple models without re-uploading the entire context.
Exploring Supported Models and Multi-Model Capabilities
Oracle ships with first-class support for the most powerful models available in 2026:
- Default: GPT-5.4 Pro
- Additional OpenAI variants: GPT-5.4, GPT-5.1 Pro, GPT-5.1 Codex, GPT-5.2, GPT-5.2 Pro
- Google Gemini: Gemini 3.1 Pro (API), Gemini 3 Pro
- Anthropic Claude: Claude Sonnet 4.5, Claude Opus 4.1
- Any OpenRouter model ID for broader experimentation
The --models flag enables parallel execution across multiple models in a single command. Oracle aggregates cost, token usage, and responses into a clear summary, making side-by-side comparison trivial. This capability proves especially valuable when validating architectural decisions or cross-checking assumptions between different reasoning styles.
Browser mode extends accessibility further. On macOS it automates your existing Chrome session to ChatGPT or Gemini using saved cookies—no API keys required. Linux and Windows users gain the same functionality with explicit path flags or manual-login options. Auto-reattach logic even handles the long-running Pro responses that frequently timeout in manual browser sessions.
Step-by-Step Installation Guide for Oracle
Installation takes under 30 seconds and works across macOS, Linux, and Windows. Node.js 22 or higher is the only prerequisite.
Global installation (recommended):
npm install -g @steipete/oraclemacOS users with Homebrew:
brew install steipete/tap/oracleZero-install option for any platform:
npx -y @steipete/oracleFor browser mode on macOS, complete a one-time manual login:
oracle --engine browser --browser-manual-login --browser-keep-browser --browser-input-timeout 120000 -p "HI"Log in once in the opened browser window. Subsequent runs reuse the automation profile automatically.
Configuration lives in ~/.oracle/config.json (JSON5 format) for defaults such as preferred model, engine, or custom ChatGPT workspace URLs. Command-line flags always override the config file.
How to Use Oracle: From Basic Prompts to Advanced Sessions
Basic usage follows an intuitive pattern:
oracle -p "Review the TS data layer for schema drift" --file "src/**/*.ts,*/*.test.ts"The tool detects OPENAI_API_KEY and defaults to API mode; otherwise it falls back to browser automation. Add --render --copy to preview the bundle and place it on your clipboard for manual pasting.
Multi-model comparison:
oracle -p "Cross-check the data layer assumptions" --models gpt-5.4-pro,gemini-3-pro --file "src/**/*.ts"Session follow-ups preserve context across iterations:
oracle --followup release-readiness-audit -p "Re-evaluate with this new context" --file "src/**/*.ts"Interactive exploration is possible through the built-in TUI:
oracle tuiSession management commands provide complete visibility:
oracle status --hours 72
oracle session <id> --render
oracle restart <id>Real-World Use Cases That Accelerate Development
Developers report dramatic productivity gains in several recurring scenarios. Architecture reviews become instantaneous: a senior engineer attaches the entire src/ directory and asks Oracle to validate consistency against new requirements. Bug triage improves because the exact failing component, tests, and logs arrive together in context. Documentation generation produces accurate results because Oracle sees the real implementation rather than stale descriptions.
Integration with Cursor via the Model Context Protocol (MCP) and Codex skills turns Oracle into a native extension of modern IDE workflows. Teams running on Azure OpenAI simply set endpoint and deployment variables and continue using the same commands. Remote browser service (oracle serve) even allows headless execution from CI machines while leveraging a signed-in desktop profile.
Advanced Tips for Maximizing Oracle
Set --browser-auto-reattach-delay 30s --browser-auto-reattach-interval 2m for long Pro runs that would otherwise timeout. Target specific ChatGPT project folders with --chatgpt-url to keep personal history clean. Combine with OpenRouter IDs for cost-optimized experimentation without changing workflows.
For large repositories, leverage glob excludes aggressively and monitor the files report. Store recurring command templates as shell aliases or scripts for one-word invocation of complex audits. Monitor total spend through aggregated multi-model reports and set personal budgets via wrapper scripts.
Integrations and Ecosystem
Oracle integrates seamlessly into broader developer tooling. Codex users copy the provided skill into ~/.codex/skills/oracle. Cursor users add a simple .cursor/mcp.json entry pointing to oracle-mcp. Related projects such as Trimmy, CodexBar, and MCPorter extend Oracle’s capabilities further.
The Community and Future of Oracle
With 31 contributors and 32 releases in rapid succession, Oracle evolves through community feedback. Detailed documentation covers Linux quirks, Chromium forks, OpenAI endpoint configuration, and manual testing procedures. The project remains fully open source with an active issues list welcoming feature requests.
Conclusion
Oracle delivers exactly what its tagline promises: the ability to ask the oracle when you are stuck and receive answers grounded in your actual codebase. Whether you prefer zero-cost browser automation or high-throughput API execution with GPT-5.4 Pro, the tool removes friction and restores flow.
Install it today, attach your first set of files, and experience the difference that true context makes. Your next breakthrough is one command away.
