steipete/oracle

Oracle second-model review : regrouper les prompts/fichiers, déboguer, refactoriser, concevoir.

Qu'est-ce que oracle ?

Oracle est un outil CLI conçu pour regrouper votre prompt et les fichiers sélectionnés en une seule requête "one-shot" à destination d'un second modèle d'IA, lui fournissant ainsi le contexte réel du dépôt. Il prend en charge deux moteurs : `browser` (idéal pour l'utilisation avec ChatGPT et GPT-5.5 Pro, qui implique l'humain dans la boucle) et `api` (pour un accès direct à des modèles comme Claude, Gemini ou Grok, avec des coûts associés). L'utilitaire gère finement l'inclusion et l'exclusion de fichiers (glob, `.gitignore`, limite de taille), offre un mode dry-run pour estimer les tokens avant envoi, et sauvegarde les sessions pour pouvoir s'y rattacher en cas de timeout. Il est particulièrement utile pour les tâches complexes de revue de code, de débogage et de refactoring, car il permet de transmettre un maximum de contexte pertinent (structure du projet, erreurs exactes, contraintes) à un modèle externe, tout en restant maître de ce qui est partagé et en évitant les fuites de secrets.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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-pro ou un libellé ChatGPT comme --model "5.5 Pro")
  • Pièces jointes : répertoires/glob + exclusions ; évitez les secrets.

Chemin doré (rapide et fiable)

  1. Choisissez un ensemble de fichiers restreint (le moins de fichiers possible contenant toujours la vérité).
  2. Prévisualisez ce que vous allez envoyer (--dry-run + --files-report si nécessaire).
  3. Lancez en mode navigateur pour le workflow habituel GPT‑5.5 Pro ChatGPT ; utilisez l'API uniquement quand vous le souhaitez explicitement.
  4. 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-output et exit.
  • 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 : --copy est 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 .gitignore lors 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_BYTES ou maxFileSizeBytes dans ~/.oracle/config.json.

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=1 pour 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 api quand OPENAI_API_KEY est définie, sinon browser.
  • Le moteur navigateur ne prend en charge que GPT + Gemini ; utilisez --engine api pour 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 zip pour 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/**"

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-pro
    • oracle --preflight --models gpt-5.4,gemini-3-pro
    • oracle --route --model gpt-5.4
  • Si l'utilisateur souhaite utiliser OpenAI officiel, passez --provider openai ou --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.json soient 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 10m est le délai normal côté utilisateur pour l'API ; Oracle déduit le délai de transport HTTP sauf si --http-timeout est explicitement défini.
  • Si la OPENAI_API_KEY exportée est invalide et que l'utilisateur souhaite sa clé OpenAI personnelle, utilisez $one-password dans une session tmux persistante. Élément connu : API Key - OpenAI - Personal, champ api_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 build
    • node ~/Projects/oracle/dist/scripts/run-cli.js ...

Sessions + slugs (ne perdez pas votre travail)

  • Stockées dans ~/.oracle/sessions (remplacez avec ORACLE_HOME_DIR).
  • Les exécutions navigateur sauvegardent des fichiers durables dans ~/.oracle/sessions/<id>/artifacts/, y compris transcript.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
  • Utilisez --slug "<3-5 mots>" pour garder les IDs de session lisibles.
  • Une protection contre les prompts en double existe ; utilisez --force uniquement quand vous voulez vraiment une nouvelle exécution.
  • Garde-fous CLI : les exécutions sans prompt se terminent avec un code non nul ; --dry-run entre 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.

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.

Skills associés