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-prooder ein ChatGPT-Picker-Label wie--model "5.5 Pro") - Anhänge: Verzeichnisse/Globs + Ausschlüsse; keine Geheimnisse.
Goldener Pfad (schnell + zuverlässig)
- Wähle eine kompakte Dateimenge (möglichst wenige Dateien, die dennoch die Wahrheit enthalten).
- Überprüfe, was du gleich senden wirst (
--dry-run+--files-reportbei Bedarf). - 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.
- 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-outputundexit.
-
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:
--copyist 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
.gitignorebei 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_BYTESodermaxFileSizeBytesin~/.oracle/config.json.
- Standardmäßig ignorierte Verzeichnisse:
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=1fü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, wennOPENAI_API_KEYgesetzt ist, sonstbrowser. - Die Browser-Engine unterstützt nur GPT + Gemini; verwende
--engine apifü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 ziphinzu, 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/**"
- Host:
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-prooracle --preflight --models gpt-5.4,gemini-3-prooracle --route --model gpt-5.4
- Wenn der Benutzer first-party OpenAI möchte, übergib
--provider openaioder--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 10mist das normale benutzerseitige API-Deadline; Oracle leitet das HTTP-Transport-Timeout ab, es sei denn,--http-timeoutwird explizit gesetzt.- Wenn der exportierte
OPENAI_API_KEYungültig ist und der Benutzer seinen persönlichen OpenAI-Schlüssel verwenden möchte, verwende$one-passwordin einer persistenten tmux-Sitzung. Bekanntes Item:API Key - OpenAI - Personal, Feldapi_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 buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
Sitzungen + Slugs (keine Arbeit verlieren)
- Gespeichert unter
~/.oracle/sessions(überschreibe mitORACLE_HOME_DIR). - Browser-Ausführungen speichern dauerhafte Dateien unter
~/.oracle/sessions/<id>/artifacts/, einschließlichtranscript.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
- Auflisten:
- Verwende
--slug "<3-5 Wörter>", um Sitzungs-IDs lesbar zu halten. - Es gibt einen Schutz vor doppelten Prompts; verwende
--forcenur, 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-runkollidiert 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.