Oracle (CLI) — meilleure utilisation
Oracle regroupe votre prompt + les fichiers sélectionnés en une seule requête "one-shot" afin qu'un autre modèle puisse répondre avec le vrai contexte du dépôt (API ou automatisation navigateur). Considérez les résultats comme des conseils : vérifiez-les par rapport au code source et aux tests.
Cas d'utilisation principal (navigateur, GPT‑5.5 Pro)
Le workflow par défaut ici : --engine browser avec GPT‑5.5 Pro dans ChatGPT. C'est le chemin "humain dans la boucle" : cela peut prendre de ~10 minutes à ~1 heure ; attendez-vous à une session sauvegardée à laquelle vous pouvez vous rattacher.
Valeurs par défaut recommandées :
- Moteur : browser (
--engine browser) - Modèle : GPT‑5.5 Pro (
--model gpt-5.5-proou un libellé ChatGPT comme--model "5.5 Pro") - Pièces jointes : répertoires/glob + exclusions ; évitez les secrets.
Chemin doré (rapide et fiable)
- Choisissez un ensemble de fichiers restreint (le moins de fichiers possible contenant toujours la vérité).
- Prévisualisez ce que vous allez envoyer (
--dry-run+--files-reportsi nécessaire). - Lancez en mode navigateur pour le workflow habituel GPT‑5.5 Pro ChatGPT ; utilisez l'API uniquement quand vous le souhaitez explicitement.
- Si l'exécution se détache / expire : rattachez-vous à la session sauvegardée (ne relancez pas).
Commandes (recommandées)
-
Afficher l'aide (une fois par session) :
npx -y @steipete/oracle --help
-
Prévisualisation (sans tokens) :
npx -y @steipete/oracle --dry-run summary -p "<tâche>" --file "src/**" --file "!**/*.test.*"npx -y @steipete/oracle --dry-run full -p "<tâche>" --file "src/**"
-
Estimation tokens/coûts :
npx -y @steipete/oracle --dry-run summary --files-report -p "<tâche>" --file "src/**"
-
Trace de démarrage/perf :
npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<tâche>" --file "src/**"- Utilisez-la quand le démarrage CLI ou le temps jusqu'au premier résultat semble lent ; inspectez
first-outputetexit.
-
Exécution navigateur (chemin principal ; les longues exécutions sont normales) :
npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<tâche>" --file "src/**"
-
Solution de repli collage manuel (assembler le lot, copier dans le presse-papier) :
npx -y @steipete/oracle --render --copy -p "<tâche>" --file "src/**"- Note :
--copyest un alias caché pour--copy-markdown.
Attacher des fichiers (--file)
--file accepte des fichiers, répertoires et globs. Vous pouvez le passer plusieurs fois ; les entrées peuvent être séparées par des virgules.
-
Inclusion :
--file "src/**"(glob de répertoire)--file src/index.ts(fichier littéral)--file docs --file README.md(répertoire + fichier littéral)
-
Exclusion (préfixez avec
!) :--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
-
Valeurs par défaut (comportement important de l'implémentation) :
- Répertoires ignorés par défaut :
node_modules,dist,coverage,.git,.turbo,.next,build,tmp(ignorés sauf si vous les passez explicitement comme répertoires/fichiers littéraux). - Honore
.gitignorelors de l'expansion des globs. - Ne suit pas les liens symboliques (l'expansion des globs utilise
followSymbolicLinks: false). - Les fichiers cachés (dotfiles) sont filtrés sauf si vous optez explicitement avec un motif incluant un point (ex.
--file ".github/**"). - Limite par défaut : les fichiers > 1 Mo sont rejetés sauf si vous augmentez
ORACLE_MAX_FILE_SIZE_BYTESoumaxFileSizeBytesdans~/.oracle/config.json.
- Répertoires ignorés par défaut :
Budget + observabilité
- Objectif : garder l'entrée totale sous ~196k tokens.
- Utilisez
--files-report(et/ou--dry-run json) pour repérer les consommateurs de tokens avant de dépenser. - Utilisez
--perf-trace/ORACLE_PERF_TRACE=1pour les temps de démarrage et de premier résultat. Les traces masquent les prompts, tokens, clés, cookies et charges utiles de cookies en ligne ; les enfants API détachés écrivent une trace secondaire suffixée par la session. - Si vous avez besoin de réglages avancés/cachés :
npx -y @steipete/oracle --help --verbose.
Moteurs (API vs navigateur)
- Sélection automatique : utilise
apiquandOPENAI_API_KEYest définie, sinonbrowser. - Le moteur navigateur ne prend en charge que GPT + Gemini ; utilisez
--engine apipour Claude/Grok/Codex ou les exécutions multi-modèles. - Les exécutions API nécessitent un consentement explicite de l'utilisateur avant de démarrer car elles engendrent des coûts d'utilisation.
- Pièces jointes navigateur :
--browser-attachments auto|never|always(auto colle en ligne jusqu'à ~60k caractères puis télécharge).- Ajoutez
--browser-bundle-files --browser-bundle-format zippour télécharger plusieurs fichiers texte sous forme d'un seul ZIP tout en préservant les noms de fichiers.
- Hôte navigateur distant (machine connectée exécute l'automatisation) :
- Hôte :
oracle serve --host 0.0.0.0 --port 9473 --token <secret> - Client :
oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<tâche>" --file "src/**"
- Hôte :
Pré-vérification API
- Les exécutions API nécessitent un consentement explicite de l'utilisateur et coûtent de l'argent.
- Avant les exécutions API, vérifiez l'état de préparation du fournisseur sans afficher les secrets :
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
- Si l'utilisateur souhaite utiliser OpenAI officiel, passez
--provider openaiou--no-azure. Cela empêche les variables d'environnement/config Azure exportées de détourner la route :oracle --provider openai --engine api --model gpt-5.5-pro ...
- Pour les panneaux multi-modèles consultatifs où un succès partiel est utile, utilisez
--allow-partial --write-output <chemin>afin que les fichiers de modèles réussis et le manifeste<tige>.oracle.jsonsoient faciles à récupérer :oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<tâche>"
--timeout 10mest le délai normal côté utilisateur pour l'API ; Oracle déduit le délai de transport HTTP sauf si--http-timeoutest explicitement défini.- Si la
OPENAI_API_KEYexportée est invalide et que l'utilisateur souhaite sa clé OpenAI personnelle, utilisez$one-passworddans une session tmux persistante. Élément connu :API Key - OpenAI - Personal, champapi_key. Injectez uniquement dans la commande Oracle ; n'imprimez jamais la clé :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 ...
- Pour déboguer Oracle lui-même, préférez le dépôt local après avoir cloné
~/Projects/oracle:pnpm -C ~/Projects/oracle run buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
Sessions + slugs (ne perdez pas votre travail)
- Stockées dans
~/.oracle/sessions(remplacez avecORACLE_HOME_DIR). - Les exécutions navigateur sauvegardent des fichiers durables dans
~/.oracle/sessions/<id>/artifacts/, y compristranscript.md, les rapports Deep Research et les images générées par ChatGPT téléchargées lorsqu'elles sont disponibles. - Les exécutions peuvent se détacher ou prendre beaucoup de temps (navigateur/API + GPT‑5.5 Pro arrive souvent). Si la CLI expire : ne relancez pas ; rattachez-vous.
- Lister :
oracle status --hours 72 - Rattacher :
oracle session <id> --render
- Lister :
- Utilisez
--slug "<3-5 mots>"pour garder les IDs de session lisibles. - Une protection contre les prompts en double existe ; utilisez
--forceuniquement quand vous voulez vraiment une nouvelle exécution. - Garde-fous CLI : les exécutions sans prompt se terminent avec un code non nul ;
--dry-runentre en conflit avec--render/--render-markdown; Ctrl-C termine les exécutions API au premier plan avec le code 130 tandis que le nettoyage/reattach du navigateur continue.
Modèle de prompt (haute qualité)
Oracle commence sans connaissance du projet. Supposez que le modèle ne peut pas déduire votre stack, vos outils de build, vos conventions ou les chemins "évidents". Incluez :
- Présentation du projet (stack + commandes de build/test + contraintes de plateforme).
- "Où se trouvent les choses" (répertoires clés, points d'entrée, fichiers de configuration, limites de dépendances).
- Question exacte + ce que vous avez essayé + le texte d'erreur (textuellement).
- Contraintes ("ne changez pas X", "doit conserver l'API publique", "budget de performance", etc.).
- Résultat souhaité ("retournez un plan de patch + tests", "listez les hypothèses risquées", "donnez 3 options avec leurs compromis").
Modèle de "prompt exhaustif" (pour restauration ultérieure)
Quand vous savez que ce sera une longue investigation, écrivez un prompt qui peut se tenir seul plus tard :
- Haut : 6 à 30 phrases de présentation du projet + objectif actuel.
- Milieu : étapes de reproduction concrètes + erreurs exactes + ce que vous avez déjà essayé.
- Bas : attachez tous les fichiers de contexte nécessaires pour qu'un nouveau modèle puisse comprendre complètement (points d'entrée, fichiers de configuration, modules clés, docs).
Si vous devez reproduire le même contexte plus tard, relancez avec le même prompt + l'ensemble --file … (les exécutions Oracle sont "one-shot" ; le modèle ne se souvient pas des exécutions précédentes).
Sécurité
- N'attachez pas de secrets par défaut (
.env, fichiers de clés, jetons d'authentification). Rédigez de manière agressive ; partagez uniquement ce qui est nécessaire. - Préférez "juste assez de contexte" : moins de fichiers + un meilleur prompt surpassent les vidages de dépôt entier.