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-proo una etiqueta del selector de ChatGPT como--model "5.5 Pro") - Archivos adjuntos: directorios/globos + exclusiones; evita secretos.
Ruta dorada (rápida y confiable)
- Elige un conjunto de archivos ajustado (la menor cantidad de archivos que aún contengan la verdad).
- Previsualiza lo que estás a punto de enviar (
--dry-run+--files-reportcuando sea necesario). - Ejecuta en modo navegador para el flujo de trabajo habitual de GPT‑5.5 Pro ChatGPT; usa API solo cuando lo quieras explícitamente.
- 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-outputyexit.
-
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:
--copyes 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
.gitignoreal 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_BYTESomaxFileSizeBytesen~/.oracle/config.json.
- Directorios ignorados por defecto:
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=1para 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
apicuandoOPENAI_API_KEYestá configurada, de lo contrariobrowser. - El motor de navegador solo admite GPT + Gemini; usa
--engine apipara 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 zippara 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/**"
- Host:
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-prooracle --preflight --models gpt-5.4,gemini-3-prooracle --route --model gpt-5.4
- Si el usuario quiere OpenAI de primera parte, pasa
--provider openaio--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.jsonsean 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 10mes el plazo de API predeterminado orientado al usuario; Oracle deduce el tiempo de espera de transporte HTTP a menos que--http-timeoutse establezca explícitamente.- Si la
OPENAI_API_KEYexportada no es válida y el usuario quiere su clave OpenAI personal, usa$one-passworden una sesión tmux persistente. Elemento conocido:API Key - OpenAI - Personal, campoapi_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 buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
Sesiones + slugs (no pierdas trabajo)
- Almacenadas en
~/.oracle/sessions(anula conORACLE_HOME_DIR). - Las ejecuciones del navegador guardan archivos duraderos en
~/.oracle/sessions/<id>/artifacts/, incluyendotranscript.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
- Listar:
- Usa
--slug "<3-5 palabras>"para mantener los IDs de sesión legibles. - Existe un guardia contra prompts duplicados; usa
--forcesolo 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-runentra 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.