Oracle (CLI) — Melhor Uso
O Oracle agrupa seu prompt + arquivos selecionados em uma única solicitação "one-shot" para que outro modelo possa responder com contexto real do repositório (API ou automação de navegador). Trate os resultados como consultivos: verifique sempre contra o código base e os testes.
Caso de uso principal (navegador, GPT‑5.5 Pro)
Fluxo de trabalho padrão aqui: --engine browser com GPT‑5.5 Pro no ChatGPT. Este é o caminho "humano no loop": pode levar de ~10 minutos a ~1 hora; espera-se uma sessão armazenada à qual você pode se reconectar.
Padrões recomendados:
- Engine: browser (
--engine browser) - Modelo: GPT‑5.5 Pro (
--model gpt-5.5-proou um rótulo do seletor do ChatGPT como--model "5.5 Pro") - Anexos: diretórios/globs + exclusões; evite segredos.
Caminho dourado (rápido + confiável)
- Selecione um conjunto enxuto de arquivos (o menor número que ainda contém a verdade).
- Visualize o que está prestes a enviar (
--dry-run+--files-reportquando necessário). - Execute no modo navegador para o fluxo de trabalho usual do GPT‑5.5 Pro no ChatGPT; use a API apenas quando explicitamente desejado.
- Se a execução for desconectada/expirar: reconecte-se à sessão armazenada (não reexecute).
Comandos (preferidos)
-
Exibir ajuda (uma vez/sessão):
npx -y @steipete/oracle --help
-
Visualizar (sem tokens):
npx -y @steipete/oracle --dry-run summary -p "<tarefa>" --file "src/**" --file "!**/*.test.*"npx -y @steipete/oracle --dry-run full -p "<tarefa>" --file "src/**"
-
Sanidade de tokens/custo:
npx -y @steipete/oracle --dry-run summary --files-report -p "<tarefa>" --file "src/**"
-
Rastreamento de inicialização/desempenho:
npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<tarefa>" --file "src/**"- Use quando a inicialização da CLI ou o tempo até a primeira saída parecer lento; inspecione
first-outputeexit.
-
Execução no navegador (caminho principal; execução longa é normal):
npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<tarefa>" --file "src/**"
-
Alternativa de colagem manual (montar pacote, copiar para a área de transferência):
npx -y @steipete/oracle --render --copy -p "<tarefa>" --file "src/**"- Nota:
--copyé um alias oculto para--copy-markdown.
Anexando arquivos (--file)
--file aceita arquivos, diretórios e globs. Você pode passá-lo várias vezes; as entradas podem ser separadas por vírgula.
-
Incluir:
--file "src/**"(glob de diretório)--file src/index.ts(arquivo literal)--file docs --file README.md(diretório + arquivo literais)
-
Excluir (prefixar com
!):--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
-
Padrões (comportamento importante da implementação):
- Diretórios ignorados por padrão:
node_modules,dist,coverage,.git,.turbo,.next,build,tmp(ignorados a menos que você os passe explicitamente como dirs/arquivos literais). - Respeita
.gitignoreao expandir globs. - Não segue links simbólicos (a expansão de glob usa
followSymbolicLinks: false). - Arquivos de ponto são filtrados a menos que você opte explicitamente por um padrão que inclua um segmento de ponto (ex.:
--file ".github/**"). - Limite padrão: arquivos > 1 MB são rejeitados a menos que você aumente
ORACLE_MAX_FILE_SIZE_BYTESoumaxFileSizeBytesem~/.oracle/config.json.
- Diretórios ignorados por padrão:
Orçamento + observabilidade
- Objetivo: manter a entrada total abaixo de ~196k tokens.
- Use
--files-report(e/ou--dry-run json) para identificar os consumidores de tokens antes de gastar. - Use
--perf-trace/ORACLE_PERF_TRACE=1para temporização da inicialização e da primeira saída. Os traces ocultam prompts, tokens, chaves, cookies e payloads de cookies inline; filhos da API destacados escrevem um trace sidecar com sufixo de sessão. - Se precisar de opções avançadas/ocultas:
npx -y @steipete/oracle --help --verbose.
Engines (API vs navegador)
- Escolha automática: usa
apiquandoOPENAI_API_KEYestá definida, caso contráriobrowser. - O engine navegador suporta apenas GPT + Gemini; use
--engine apipara Claude/Grok/Codex ou execuções com múltiplos modelos. - Execuções via API requerem consentimento explícito do usuário antes de iniciar, pois incorrem em custos de uso.
- Anexos do navegador:
--browser-attachments auto|never|always(auto cola inline até ~60k caracteres e depois faz upload).- Adicione
--browser-bundle-files --browser-bundle-format zippara fazer upload de muitos arquivos de texto como um único ZIP preservando os nomes dos arquivos.
- Host de navegador remoto (máquina autenticada executa a automação):
- Host:
oracle serve --host 0.0.0.0 --port 9473 --token <segredo> - Cliente:
oracle --engine browser --remote-host <host:porta> --remote-token <segredo> -p "<tarefa>" --file "src/**"
- Host:
Verificação prévia da API
- Execuções via API requerem consentimento explícito do usuário e custam dinheiro.
- Antes das execuções da API, verifique a prontidão do provedor sem imprimir segredos:
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
- Se o usuário quiser OpenAI de primeira parte, passe
--provider openaiou--no-azure. Isso impede que o ambiente/ config Azure exportado sequestre a rota:oracle --provider openai --engine api --model gpt-5.5-pro ...
- Para painéis com múltiplos modelos consultivos onde o sucesso parcial é útil, use
--allow-partial --write-output <caminho>para que os arquivos de modelo bem-sucedidos e o manifesto<stem>.oracle.jsonsejam fáceis de recuperar:oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<tarefa>"
--timeout 10mé o prazo normal da API voltada ao usuário; o Oracle deriva o tempo limite de transporte HTTP a menos que--http-timeoutseja explicitamente definido.- Se a
OPENAI_API_KEYexportada for inválida e o usuário quiser sua chave OpenAI pessoal, use$one-passwordem uma sessão tmux persistente. Item conhecido:API Key - OpenAI - Personal, campoapi_key. Injete apenas no comando Oracle único; nunca imprima a chave: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 o próprio Oracle, prefira o checkout local após puxar
~/Projects/oracle:pnpm -C ~/Projects/oracle run buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
Sessões + slugs (não perca trabalho)
- Armazenadas em
~/.oracle/sessions(substitua comORACLE_HOME_DIR). - As execuções no navegador salvam arquivos duráveis em
~/.oracle/sessions/<id>/artifacts/, incluindotranscript.md, relatórios do Deep Research e imagens geradas pelo ChatGPT baixadas quando disponíveis. - As execuções podem ser desconectadas ou demorar muito (navegador/API + GPT‑5.5 Pro geralmente é assim). Se a CLI expirar: não reexecute; reconecte-se.
- Listar:
oracle status --hours 72 - Anexar:
oracle session <id> --render
- Listar:
- Use
--slug "<3-5 palavras>"para manter os IDs de sessão legíveis. - Existe proteção contra prompts duplicados; use
--forceapenas quando realmente quiser uma nova execução. - Salvaguardas da CLI: execuções como root sem um prompt saem com código não zero;
--dry-runconflita com--render/--render-markdown; Ctrl-C sai das execuções da API em primeiro plano com código 130 enquanto a limpeza/reconexão do navegador ainda é executada.
Modelo de prompt (alto sinal)
O Oracle começa com zero conhecimento do projeto. Presuma que o modelo não pode inferir sua stack, ferramentas de build, convenções ou caminhos "óbvios". Inclua:
- Briefing do projeto (stack + comandos de build/teste + restrições de plataforma).
- "Onde as coisas estão" (diretórios principais, pontos de entrada, arquivos de configuração, limites de dependência).
- Pergunta exata + o que você tentou + o texto do erro (textualmente).
- Restrições ("não mude X", "deve manter API pública", "orçamento de desempenho", etc).
- Saída desejada ("retorne plano de patch + testes", "liste suposições arriscadas", "dê 3 opções com prós e contras").
Padrão "prompt exaustivo" (para restauração posterior)
Quando você sabe que será uma investigação longa, escreva um prompt que possa ser usado sozinho posteriormente:
- Topo: briefing do projeto de 6 a 30 frases + objetivo atual.
- Meio: passos de reprodução concretos + erros exatos + o que você já tentou.
- Base: anexe todos os arquivos de contexto necessários para que um novo modelo possa entender completamente (pontos de entrada, configurações, módulos chave, docs).
Se você precisar reproduzir o mesmo contexto posteriormente, execute novamente com o mesmo prompt + conjunto --file … (as execuções do Oracle são one-shot; o modelo não se lembra de execuções anteriores).
Segurança
- Não anexe segredos por padrão (
.env, arquivos de chave, tokens de autenticação). Redija agressivamente; compartilhe apenas o necessário. - Prefira "contexto apenas suficiente": menos arquivos + melhor prompt superam despejos de repositório inteiro.