oracle

Was macht oracle?

Oracle bündelt einen Prompt + ausgewählte Dateien für einen zweiten Modell-Durchlauf. Behandle die Ausgabe als beratend; überprüfe sie gegen Code + Tests.

Hauptpfad

Aktuelles CLI-Standardmodell: gpt-5.5-pro. Die Browser-Engine ist nützlich für lange ChatGPT Pro-Läufe; die API-Engine ist nützlich, wenn OPENAI_API_KEY oder eine Azure-Konfiguration bereit ist.

Empfohlene Standardeinstellungen:

• Zuerst Vorschau: --dry-run summary --files-report
• Langer Browser-Lauf: --engine browser --model gpt-5.5-pro
• Explizite API: --engine api --model gpt-5.5

Goldener Pfad

1. Wähle einen kompakten Dateisatz (möglichst wenige Dateien, die dennoch die Wahrheit enthalten).
2. Vorschau des Payloads + Token-Verbrauch (--dry-run + --files-report).
3. Verwende den Browser-Modus für langes Pro-Denken; API-Modus für explizite API-Aufrufe.
4. Falls der Lauf sich trennt / ein Timeout auftritt: stelle die Verbindung zur gespeicherten Sitzung wieder her. Führe nicht blind erneut aus.

Befehle (bevorzugt)

• Hilfe:

  • oracle --help
  • Falls die Binärdatei nicht installiert ist: npx -y @steipete/oracle --help (vermeide pnpx; sqlite-Bindungen).

• Vorschau (keine Token):

  • oracle --dry-run summary -p "<aufgabe>" --file "src/**" --file "!**/*.test.*"
  • oracle --dry-run full -p "<aufgabe>" --file "src/**"

• Token-Sanity:

  • oracle --dry-run summary --files-report -p "<aufgabe>" --file "src/**"

• Browser-Lauf (Hauptpfad; lange Laufzeit ist normal):

  • oracle --engine browser --model gpt-5.5-pro -p "<aufgabe>" --file "src/**"

• Manuelle Einfüge-Fallback:

  • oracle --render --copy -p "<aufgabe>" --file "src/**"
  • Hinweis: --copy ist ein verstecktes Alias für --copy-markdown.

Dateien anhängen (--file)

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

• Einschließen:

  • --file "src/**"
  • --file src/index.ts
  • --file docs --file README.md

• Ausschließen:

  • --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

• Standardverhalten (Implementierung):

  • Standardmäßig ignorierte Verzeichnisse: node_modules, dist, coverage, .git, .turbo, .next, build, tmp (übersprungen, sofern nicht explizit als Literal-Verzeichnisse/-Dateien übergeben).
  • Beachtet .gitignore beim Expandieren von Globs.
  • Folgt keinen symbolischen Links.
  • Dotfiles werden herausgefiltert, es sei denn, sie werden per Muster eingeschlossen (z. B. --file ".github/**").
  • Dateien > 1 MB werden abgelehnt.

Engines (API vs. Browser)

• Automatische Auswahl: api, wenn OPENAI_API_KEY gesetzt ist; sonst browser.
• Der Browser unterstützt nur GPT + Gemini; verwende --engine api für Claude/Grok/Codex oder Multi-Modell-Läufe.
• Browser-Anhänge:
  • --browser-attachments auto|never|always (fügt inline bis zu ~60k Zeichen automatisch ein und lädt dann hoch).
• Remote-Browser-Host:
  • Host: oracle serve --host 0.0.0.0 --port 9473 --token <geheim>
  • Client: oracle --engine browser --remote-host <host:port> --remote-token <geheim> -p "<aufgabe>" --file "src/**"

Sitzungen + Slugs

• Gespeichert unter ~/.oracle/sessions (überschreibbar mit ORACLE_HOME_DIR).
• Läufe können sich trennen oder lange dauern (Browser + Pro ist oft so). Falls das CLI ein Timeout hat: nicht erneut ausführen; stelle die Verbindung wieder her.
  • Auflisten: oracle status --hours 72
  • Anhängen: 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 einen neuen Lauf möchtest.

Prompt-Vorlage (hohe Signalstärke)

Oracle startet mit null Projektkenntnis. 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 leben“ (wichtige Verzeichnisse, Einstiegspunkte, Konfigurationsdateien, Grenzen).
• Genaue Frage + was du versucht hast + den Fehlertext (wörtlich).
• Einschränkungen („ändere X nicht“, „muss öffentliche API erhalten“, usw.).
• Gewünschte Ausgabe („Patch-Plan + Tests zurückgeben“, „3 Optionen mit Kompromissen nennen“).

Anhänge

• Lasse .env, Schlüsseldateien und Authentifizierungs-Token aus den Anhängen, es sei denn, der Benutzer bittet darum, sie einzuschließen.

Muster zur Wiederherstellung des „erschöpfenden Prompts“

Für lange Untersuchungen schreibe einen eigenständigen Prompt + Dateisatz, damit du Tage später erneut ausführen kannst:

• 6-30 Sätze Projekt-Briefing + das Ziel.
• Reproduktionsschritte + genaue Fehler + was du versucht hast.
• Hänge alle benötigten Kontextdateien an (Einstiegspunkte, Konfigurationen, Schlüsselmodule, Dokumente).

Oracle-Läufe sind Einzelschuss; das Modell erinnert sich nicht an frühere Läufe. „Kontext wiederherstellen“ bedeutet, mit dem gleichen Prompt + --file …-Satz erneut auszuführen (oder eine noch laufende gespeicherte Sitzung wieder anzuhängen).