steipete/oracle

Revisão de segundo modelo com Oracle: agrupar prompts/arquivos, depurar, refatorar, projetar.

O que é oracle?

O Oracle (CLI) é uma ferramenta especializada que encapsula seu prompt e arquivos selecionados em uma única solicitação "one-shot", otimizada para que outro modelo de IA responda com contexto real do repositório, seja via API ou automação de navegador. Sua principal utilidade é permitir que desenvolvedores submetam tarefas complexas de revisão, depuração, refatoração e design para modelos avançados como o GPT-5.5 Pro, mantendo o fluxo de trabalho "human-in-the-loop" durante sessões longas que podem durar de minutos a horas. O Oracle suporta tanto a execução via navegador (ideal para sessões interativas no ChatGPT) quanto via API (para provedores como Claude, Gemini e Codex), oferecendo controle granular sobre quais arquivos incluir, excluir e como orçar tokens. A ferramenta é particularmente útil para projetos onde o contexto completo do código é essencial para uma análise precisa, e seus relatórios de custo e desempenho ajudam a evitar desperdícios. O tratamento de sessões permite recuperar trabalhos interrompidos sem precisar reexecutar a análise.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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-pro ou 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)

  1. Selecione um conjunto enxuto de arquivos (o menor número que ainda contém a verdade).
  2. Visualize o que está prestes a enviar (--dry-run + --files-report quando necessário).
  3. Execute no modo navegador para o fluxo de trabalho usual do GPT‑5.5 Pro no ChatGPT; use a API apenas quando explicitamente desejado.
  4. 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-output e exit.
  • 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 .gitignore ao 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_BYTES ou maxFileSizeBytes em ~/.oracle/config.json.

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=1 para 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 api quando OPENAI_API_KEY está definida, caso contrário browser.
  • O engine navegador suporta apenas GPT + Gemini; use --engine api para 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 zip para 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/**"

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-pro
    • oracle --preflight --models gpt-5.4,gemini-3-pro
    • oracle --route --model gpt-5.4
  • Se o usuário quiser OpenAI de primeira parte, passe --provider openai ou --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.json sejam 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-timeout seja explicitamente definido.
  • Se a OPENAI_API_KEY exportada for inválida e o usuário quiser sua chave OpenAI pessoal, use $one-password em uma sessão tmux persistente. Item conhecido: API Key - OpenAI - Personal, campo api_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 build
    • node ~/Projects/oracle/dist/scripts/run-cli.js ...

Sessões + slugs (não perca trabalho)

  • Armazenadas em ~/.oracle/sessions (substitua com ORACLE_HOME_DIR).
  • As execuções no navegador salvam arquivos duráveis em ~/.oracle/sessions/<id>/artifacts/, incluindo transcript.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
  • Use --slug "<3-5 palavras>" para manter os IDs de sessão legíveis.
  • Existe proteção contra prompts duplicados; use --force apenas 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-run conflita 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.

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.

Habilidades Relacionadas