CommunityProgramación y desarrollogithub.com

steipete/oracle

Revisión de modelo Oracle: agrupa prompts y archivos, depura, refactoriza, diseña.

¿Qué es oracle?

Oracle es una herramienta de línea de comandos (CLI) diseñada para empaquetar tu prompt junto con archivos seleccionados del repositorio en una única solicitud 'one-shot', permitiendo que otro modelo de lenguaje (como GPT-5.5 Pro) responda con el contexto real del proyecto. Su propósito principal es facilitar revisiones de código, depuración, refactorización y diseño de alta calidad al proporcionar información completa a un modelo externo, evitando límites de contexto o falta de conocimiento del código. Soporta dos modos de ejecución principal: navegador (ChatGPT) para un flujo interactivo supervisado, o API para acceder directamente a modelos como Claude, Gemini, o GPT, aunque este último requiere consentimiento explícito debido a costos. Permite un control detallado sobre los archivos incluidos mediante patrones glob, exclusión de secretos, y manejo inteligente de grandes conjuntos de archivos, con un límite de tokens de ~196k y herramientas de presupuesto y observabilidad integradas.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Oracle (CLI) — mejor uso

Oracle agrupa tu prompt + archivos seleccionados en una única solicitud "one-shot" para que otro modelo pueda responder con el contexto real del repositorio (API o automatización del navegador). Trata los resultados como asesoramiento: verifica contra el código base y las pruebas.

Caso de uso principal (navegador, GPT‑5.5 Pro)

El flujo de trabajo predeterminado aquí es: --engine browser con GPT‑5.5 Pro en ChatGPT. Esta es la ruta "humano en el circuito": puede tomar de ~10 minutos a ~1 hora; espera tener una sesión almacenada a la que puedas reconectarte.

Valores predeterminados recomendados:

  • Motor: navegador (--engine browser)
  • Modelo: GPT‑5.5 Pro (--model gpt-5.5-pro o una etiqueta del selector de ChatGPT como --model "5.5 Pro")
  • Archivos adjuntos: directorios/globos + exclusiones; evita secretos.

Ruta dorada (rápida y confiable)

  1. Elige un conjunto de archivos ajustado (la menor cantidad de archivos que aún contengan la verdad).
  2. Previsualiza lo que estás a punto de enviar (--dry-run + --files-report cuando sea necesario).
  3. Ejecuta en modo navegador para el flujo de trabajo habitual de GPT‑5.5 Pro ChatGPT; usa API solo cuando lo quieras explícitamente.
  4. Si la ejecución se separa/agota el tiempo: reconéctate a la sesión almacenada (no vuelvas a ejecutar).

Comandos (preferidos)

  • Mostrar ayuda (una vez/sesión):

    • npx -y @steipete/oracle --help
  • Previsualización (sin tokens):

    • npx -y @steipete/oracle --dry-run summary -p "<tarea>" --file "src/**" --file "!**/*.test.*"
    • npx -y @steipete/oracle --dry-run full -p "<tarea>" --file "src/**"
  • Cordura de tokens/costos:

    • npx -y @steipete/oracle --dry-run summary --files-report -p "<tarea>" --file "src/**"
  • Traza de inicio/rendimiento:

    • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<tarea>" --file "src/**"
    • Úsalo cuando el inicio de la CLI o el tiempo hasta la primera salida se sientan lentos; inspecciona first-output y exit.
  • Ejecución en navegador (ruta principal; larga duración es normal):

    • npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<tarea>" --file "src/**"
  • Alternativa de pegado manual (ensamblar paquete, copiar al portapapeles):

    • npx -y @steipete/oracle --render --copy -p "<tarea>" --file "src/**"
    • Nota: --copy es un alias oculto para --copy-markdown.

Adjuntar archivos (--file)

--file acepta archivos, directorios y globos. Puedes pasarlo varias veces; las entradas pueden estar separadas por comas.

  • Incluir:

    • --file "src/**" (globo de directorio)
    • --file src/index.ts (archivo literal)
    • --file docs --file README.md (directorio + archivo literal)
  • Excluir (prefijo con !):

    • --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
  • Valores predeterminados (comportamiento importante de la implementación):

    • Directorios ignorados por defecto: node_modules, dist, coverage, .git, .turbo, .next, build, tmp (omitidos a menos que los pases explícitamente como directorios/archivos literales).
    • Respeta .gitignore al expandir globos.
    • No sigue enlaces simbólicos (la expansión de globos usa followSymbolicLinks: false).
    • Los archivos ocultos (dotfiles) se filtran a menos que optes explícitamente con un patrón que incluya un segmento de punto (ej. --file ".github/**").
    • Límite predeterminado: archivos > 1 MB son rechazados a menos que aumentes ORACLE_MAX_FILE_SIZE_BYTES o maxFileSizeBytes en ~/.oracle/config.json.

Presupuesto + observabilidad

  • Objetivo: mantener la entrada total por debajo de ~196k tokens.
  • Usa --files-report (y/o --dry-run json) para detectar los grandes consumidores de tokens antes de gastar.
  • Usa --perf-trace / ORACLE_PERF_TRACE=1 para tiempos de inicio y primera salida. Las trazas redactan prompts, tokens, claves, cookies y cargas útiles de cookies en línea; los procesos secundarios de API separados escriben una traza lateral con sufijo de sesión.
  • Si necesitas parámetros ocultos/avanzados: npx -y @steipete/oracle --help --verbose.

Motores (API vs navegador)

  • Selección automática: usa api cuando OPENAI_API_KEY está configurada, de lo contrario browser.
  • El motor de navegador solo admite GPT + Gemini; usa --engine api para Claude/Grok/Codex o ejecuciones con múltiples modelos.
  • Las ejecuciones de API requieren consentimiento explícito del usuario antes de comenzar porque incurren en costos de uso.
  • Archivos adjuntos del navegador:
    • --browser-attachments auto|never|always (auto pega en línea hasta ~60k caracteres y luego sube).
    • Agrega --browser-bundle-files --browser-bundle-format zip para subir muchos archivos de texto como un solo ZIP preservando los nombres de archivo.
  • Host remoto del navegador (máquina con sesión iniciada ejecuta la automatización):
    • Host: oracle serve --host 0.0.0.0 --port 9473 --token <secreto>
    • Cliente: oracle --engine browser --remote-host <host:puerto> --remote-token <secreto> -p "<tarea>" --file "src/**"

Verificación previa a API

  • Las ejecuciones de API requieren consentimiento explícito del usuario y cuestan dinero.
  • Antes de las ejecuciones de API, verifica la preparación del proveedor sin imprimir secretos:
    • 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 el usuario quiere OpenAI de primera parte, pasa --provider openai o --no-azure. Esto evita que las variables de entorno/configuración de Azure exportadas secuestren la ruta:
    • oracle --provider openai --engine api --model gpt-5.5-pro ...
  • Para paneles de múltiples modelos donde el éxito parcial es útil, usa --allow-partial --write-output <ruta> para que los archivos de modelo exitosos y el manifiesto <raíz>.oracle.json sean fáciles de recuperar:
    • oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<tarea>"
  • --timeout 10m es el plazo de API predeterminado orientado al usuario; Oracle deduce el tiempo de espera de transporte HTTP a menos que --http-timeout se establezca explícitamente.
  • Si la OPENAI_API_KEY exportada no es válida y el usuario quiere su clave OpenAI personal, usa $one-password en una sesión tmux persistente. Elemento conocido: API Key - OpenAI - Personal, campo api_key. Inyecta solo en el comando individual de Oracle; nunca imprimas la clave:
    • 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 ...
  • Para depurar Oracle en sí, prefiere el checkout local después de hacer pull de ~/Projects/oracle:
    • pnpm -C ~/Projects/oracle run build
    • node ~/Projects/oracle/dist/scripts/run-cli.js ...

Sesiones + slugs (no pierdas trabajo)

  • Almacenadas en ~/.oracle/sessions (anula con ORACLE_HOME_DIR).
  • Las ejecuciones del navegador guardan archivos duraderos en ~/.oracle/sessions/<id>/artifacts/, incluyendo transcript.md, informes de Deep Research e imágenes descargadas generadas por ChatGPT cuando estén disponibles.
  • Las ejecuciones pueden separarse o tomar mucho tiempo (navegador/API + GPT‑5.5 Pro a menudo lo hace). Si la CLI agota el tiempo: no vuelvas a ejecutar; reconéctate.
    • Listar: oracle status --hours 72
    • Conectar: oracle session <id> --render
  • Usa --slug "<3-5 palabras>" para mantener los IDs de sesión legibles.
  • Existe un guardia contra prompts duplicados; usa --force solo cuando realmente quieras una ejecución nueva.
  • Barreras de seguridad de la CLI: las ejecuciones raíz sin un prompt salen con código distinto de cero; --dry-run entra en conflicto con --render / --render-markdown; Ctrl-C sale de las ejecuciones de API en primer plano con código 130 mientras la limpieza del navegador/reconexión aún se ejecuta.

Plantilla de prompt (alta señal)

Oracle comienza con cero conocimiento del proyecto. Asume que el modelo no puede inferir tu stack, herramientas de compilación, convenciones o rutas "obvias". Incluye:

  • Información del proyecto (stack + comandos de compilación/prueba + restricciones de la plataforma).
  • "Dónde están las cosas" (directorios clave, puntos de entrada, archivos de configuración, límites de dependencias).
  • Pregunta exacta + lo que intentaste + el texto del error (textual).
  • Restricciones ("no cambies X", "debe mantener la API pública", "presupuesto de rendimiento", etc.).
  • Salida deseada ("devuelve plan de parche + pruebas", "enumera suposiciones riesgosas", "da 3 opciones con compensaciones").

Patrón de "prompt exhaustivo" (para restauración posterior)

Cuando sepas que esta será una investigación larga, escribe un prompt que pueda valerse por sí mismo más tarde:

  • Arriba: 6–30 oraciones de información del proyecto + objetivo actual.
  • Medio: pasos de reproducción concretos + errores exactos + lo que ya intentaste.
  • Abajo: adjunta todos los archivos de contexto necesarios para que un modelo nuevo pueda entender completamente (puntos de entrada, configuraciones, módulos clave, documentos).

Si necesitas reproducir el mismo contexto más tarde, vuelve a ejecutar con el mismo prompt + conjunto --file … (las ejecuciones de Oracle son de un solo uso; el modelo no recuerda ejecuciones anteriores).

Seguridad

  • No adjuntes secretos por defecto (.env, archivos de clave, tokens de autenticación). Redacta agresivamente; comparte solo lo necesario.
  • Prefiere "solo el contexto suficiente": menos archivos + mejor prompt superan los volcados de todo el repositorio.

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 relacionados