CommunityCodierung & Entwicklunggithub.com

steipete/oracle

Oracle Zweitmodell-Review: Prompts/Dateien bündeln, debuggen, refaktorieren, designen.

Was ist oracle?

Oracle ist ein CLI-Tool, das deinen Prompt und ausgewählte Dateien zu einer einzigen „One-Shot“-Anfrage bündelt, damit ein zweites KI-Modell (z. B. GPT‑5.5 Pro in ChatGPT) den vollständigen Repository-Kontext erhält. Es eignet sich besonders für Code-Reviews, Debugging, Refactoring und Designentscheidungen, bei denen ein frischer Blick auf den gesamten Codebase helfen soll. Oracle unterstützt zwei Ausführungsmodi: den Browser-Modus (für ChatGPT mit GPT‑5.5 Pro) und den API-Modus (für andere Modelle wie Claude, Gemini oder Grok). Der Browser-Modus ist als „Human-in-the-Loop“-Workflow konzipiert, der längere Laufzeiten in Kauf nimmt, dafür aber keine API-Kosten verursacht. Der API-Modus erfordert ausdrückliche Zustimmung, da hier Kosten anfallen. Dank umfangreicher Optionen zur Dateiauswahl (inkl. Glob-Muster, Ausschlüssen und .gitignore-Respektierung) lässt sich der Kontext präzise steuern. Oracle speichert Sitzungen, sodass du nach einem Timeout oder Abbruch problemlos wieder anknüpfen kannst, ohne die Anfrage neu starten zu müssen. Die Ausgabe ist als Beratung zu verstehen – übernimm Änderungen erst nach manueller Prüfung gegen den Codebestand und die Tests.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/oracle

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Oracle (CLI) — Beste Verwendung

Oracle bündelt deinen Prompt und ausgewählte Dateien zu einer einzigen „One-Shot“-Anfrage, damit ein anderes Modell mit echtem Repository-Kontext antworten kann (API oder Browser-Automatisierung). Behandle die Ausgaben als beratend: Überprüfe sie gegen den Codebestand und die Tests.

Hauptanwendungsfall (Browser, GPT‑5.5 Pro)

Standard-Workflow hier: --engine browser mit GPT‑5.5 Pro in ChatGPT. Dies ist der „Human-in-the-Loop“-Pfad: Es kann etwa 10 Minuten bis 1 Stunde dauern; erwarte eine gespeicherte Sitzung, an die du wieder anknüpfen kannst.

Empfohlene Standardeinstellungen:

  • Engine: Browser (--engine browser)
  • Modell: GPT‑5.5 Pro (entweder --model gpt-5.5-pro oder ein ChatGPT-Picker-Label wie --model "5.5 Pro")
  • Anhänge: Verzeichnisse/Globs + Ausschlüsse; keine Geheimnisse.

Goldener Pfad (schnell + zuverlässig)

  1. Wähle eine kompakte Dateimenge (möglichst wenige Dateien, die dennoch die Wahrheit enthalten).
  2. Überprüfe, was du gleich senden wirst (--dry-run + --files-report bei Bedarf).
  3. Führe im Browser-Modus für den üblichen GPT‑5.5 Pro ChatGPT-Workflow aus; verwende die API nur, wenn du es explizit möchtest.
  4. Wenn die Ausführung abbricht/ausläuft: knüpfe an die gespeicherte Sitzung an (nicht neu ausführen).

Befehle (bevorzugt)

  • Hilfe anzeigen (einmal pro Sitzung):

    • npx -y @steipete/oracle --help
  • Vorschau (keine Tokens):

    • npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
    • npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"
  • Token-/Kostenprüfung:

    • npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"
  • Start-/Performance-Trace:

    • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"
    • Verwende, wenn dir der CLI-Start oder die Zeit bis zur ersten Ausgabe langsam vorkommt; inspiziere first-output und exit.
  • Browser-Ausführung (Hauptpfad; lange Laufzeit ist normal):

    • npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"
  • Manuelles Einfügen als Fallback (Bündel erstellen, in Zwischenablage kopieren):

    • npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"
    • Hinweis: --copy ist ein versteckter Alias für --copy-markdown.

Dateien anhängen (--file)

--file akzeptiert Dateien, Verzeichnisse und Globs. Du kannst es mehrmals angeben; Einträge können kommagetrennt sein.

  • Einschließen:

    • --file "src/**" (Verzeichnis-Glob)
    • --file src/index.ts (konkrete Datei)
    • --file docs --file README.md (konkretes Verzeichnis + Datei)
  • Ausschließen (mit ! voranstellen):

    • --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
  • Standardverhalten (wichtiges implementierungsbedingtes Verhalten):

    • Standardmäßig ignorierte Verzeichnisse: node_modules, dist, coverage, .git, .turbo, .next, build, tmp (werden übersprungen, es sei denn, du übergibst sie explizit als konkrete Verzeichnisse/Dateien).
    • Respektiert .gitignore bei der Glob-Erweiterung.
    • Folgt keinen symbolischen Links (Glob-Erweiterung verwendet followSymbolicLinks: false).
    • Punktdateien werden herausgefiltert, es sei denn, du optierst explizit mit einem Muster, das ein Punktsegment enthält, z. B. --file ".github/**".
    • Standard-Begrenzung: Dateien > 1 MB werden abgelehnt, es sei denn, du erhöhst ORACLE_MAX_FILE_SIZE_BYTES oder maxFileSizeBytes in ~/.oracle/config.json.

Budget + Beobachtbarkeit

  • Ziel: Gesamteingabe unter ~196.000 Tokens halten.
  • Verwende --files-report (und/oder --dry-run json), um die Tokenfresser zu erkennen, bevor du sie ausgibst.
  • Verwende --perf-trace / ORACLE_PERF_TRACE=1 für das Timing von Start und erster Ausgabe. Traces redigieren Prompts, Tokens, Schlüssel, Cookies und Inline-Cookie-Payloads; losgelöste API-Kinderprozesse schreiben einen sitzungssuffigierten Sidecar-Trace.
  • Falls du versteckte/fortgeschrittene Einstellungen benötigst: npx -y @steipete/oracle --help --verbose.

Engines (API vs. Browser)

  • Automatische Auswahl: Verwendet api, wenn OPENAI_API_KEY gesetzt ist, sonst browser.
  • Die Browser-Engine unterstützt nur GPT + Gemini; verwende --engine api für Claude/Grok/Codex oder Multi-Modell-Ausführungen.
  • API-Ausführungen erfordern explizite Benutzereinwilligung vor dem Start, da sie Kosten verursachen.
  • Browser-Anhänge:
    • --browser-attachments auto|never|always (auto fügt inline bis zu ~60.000 Zeichen ein und lädt dann hoch).
    • Füge --browser-bundle-files --browser-bundle-format zip hinzu, um viele Textdateien als ein ZIP hochzuladen, während die Dateinamen erhalten bleiben.
  • Remote-Browser-Host (eingeloggter Computer führt Automatisierung aus):
    • Host: oracle serve --host 0.0.0.0 --port 9473 --token <secret>
    • Client: oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"

API-Preflight

  • API-Ausführungen erfordern explizite Benutzereinwilligung und kosten Geld.
  • Vor API-Ausführungen die Provider-Bereitschaft prüfen, ohne Geheimnisse auszugeben:
    • oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
    • oracle --preflight --models gpt-5.4,gemini-3-pro
    • oracle --route --model gpt-5.4
  • Wenn der Benutzer first-party OpenAI möchte, übergib --provider openai oder --no-azure. Dies verhindert, dass exportierte Azure-Umgebungsvariablen/Konfiguration die Route kapern:
    • oracle --provider openai --engine api --model gpt-5.5-pro ...
  • Für beratende Multi-Modell-Panels, bei denen Teilerfolge nützlich sind, verwende --allow-partial --write-output <path>, damit erfolgreiche Modelldateien und das <stem>.oracle.json-Manifest leicht wiederherstellbar sind:
    • oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<task>"
  • --timeout 10m ist das normale benutzerseitige API-Deadline; Oracle leitet das HTTP-Transport-Timeout ab, es sei denn, --http-timeout wird explizit gesetzt.
  • Wenn der exportierte OPENAI_API_KEY ungültig ist und der Benutzer seinen persönlichen OpenAI-Schlüssel verwenden möchte, verwende $one-password in einer persistenten tmux-Sitzung. Bekanntes Item: API Key - OpenAI - Personal, Feld api_key. Injiziere nur in den einzelnen Oracle-Befehl; gib den Schlüssel niemals aus:
    • OPENAI_API_KEY="$(op item get 'API Key - OpenAI - Personal' --account my.1password.com --fields label=api_key --reveal)" oracle --provider openai --engine api --model gpt-5.5-pro ...
  • Zum Debuggen von Oracle selbst bevorzuge das lokale Checkout nach dem Pull von ~/Projects/oracle:
    • pnpm -C ~/Projects/oracle run build
    • node ~/Projects/oracle/dist/scripts/run-cli.js ...

Sitzungen + Slugs (keine Arbeit verlieren)

  • Gespeichert unter ~/.oracle/sessions (überschreibe mit ORACLE_HOME_DIR).
  • Browser-Ausführungen speichern dauerhafte Dateien unter ~/.oracle/sessions/<id>/artifacts/, einschließlich transcript.md, Deep Research-Berichten und heruntergeladenen ChatGPT-generierten Bildern, sofern verfügbar.
  • Ausführungen können sich lösen oder lange dauern (Browser/API + GPT‑5.5 Pro oft). Wenn das CLI ausläuft: nicht neu ausführen; wieder anknüpfen.
    • Auflisten: oracle status --hours 72
    • Anknüpfen: oracle session <id> --render
  • Verwende --slug "<3-5 Wörter>", um Sitzungs-IDs lesbar zu halten.
  • Es gibt einen Schutz vor doppelten Prompts; verwende --force nur, wenn du wirklich eine frische Ausführung möchtest.
  • CLI-Schutzmaßnahmen: Root-Ausführungen ohne Prompt beenden mit einem Exit-Code ungleich Null; --dry-run kollidiert mit --render / --render-markdown; Strg-C beendet API-Ausführungen im Vordergrund mit Code 130, während die Browser-Bereinigung/Wiederanknüpfung noch läuft.

Prompt-Vorlage (hohe Signalstärke)

Oracle beginnt mit null Projektwissen. Gehe davon aus, dass das Modell deinen Stack, Build-Tools, Konventionen oder „offensichtliche“ Pfade nicht ableiten kann. Füge hinzu:

  • Projekt-Briefing (Stack + Build-/Test-Befehle + Plattform-Einschränkungen).
  • „Wo die Dinge liegen“ (wichtige Verzeichnisse, Einstiegspunkte, Konfigurationsdateien, Abhängigkeitsgrenzen).
  • Genaue Frage + was du versucht hast + den Fehlertext (wörtlich).
  • Einschränkungen („Ändere X nicht“, „muss öffentliche API erhalten“, „Performance-Budget“ usw.).
  • Gewünschte Ausgabe („Patch-Plan + Tests zurückgeben“, „riskante Annahmen auflisten“, „3 Optionen mit Kompromissen nennen“).

„Erschöpfender Prompt“-Muster (für spätere Wiederherstellung)

Wenn du weißt, dass dies eine lange Untersuchung wird, schreibe einen Prompt, der später eigenständig bestehen kann:

  • Oben: 6–30 Sätze Projekt-Briefing + aktuelles Ziel.
  • Mitte: konkrete Reproduktionsschritte + genaue Fehler + was du bereits versucht hast.
  • Unten: alle benötigten Kontextdateien anhängen, damit ein frisches Modell alles vollständig verstehen kann (Einstiegspunkte, Konfigurationen, Schlüsselmodule, Dokumentation).

Wenn du denselben Kontext später reproduzieren musst, führe mit demselben Prompt + --file …-Satz erneut aus (Oracle-Ausführungen sind One-Shot; das Modell erinnert sich nicht an vorherige Ausführungen).

Sicherheit

  • Standardmäßig keine Geheimnisse anhängen (.env, Schlüsseldateien, Authentifizierungstokens). Reduziere aggressiv; teile nur, was erforderlich ist.
  • Bevorzuge „gerade genug Kontext“: weniger Dateien + besserer Prompt schlagen das Dumpen des gesamten Repositorys.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

Verwandte Skills