consult-oracle

Consult Oracle

Consult ChatGPT Pro via ChatGPT browser automation for problems that resist standard approaches.

Configuration

The oracle reads from ~/.turbo/config.json:

{
  "oracle": {
    "chatgptUrl": "https://chatgpt.com/"
  }
}

| Key | Purpose | Default |

|---|---|---|

| chatgptUrl | ChatGPT URL (e.g., a custom GPT project URL) | https://chatgpt.com/ |

Step 1: Identify Key Files

Find the 2-5 files most relevant to the problem.

Step 2: Formulate the Question

Write a clear, specific problem description. Include what has already been tried and why it failed. Open with a short project briefing (stack, services, build steps). The more context, the better the response.

Step 3: Run the Oracle

Use a generous timeout (60 minutes / 3600000ms). The script loads chatgptUrl from ~/.turbo/config.json automatically and consults through the oracle's own signed-in ChatGPT profile. Generate a random tag and persist the response:

ORACLE_TAG=$(head -c 4 /dev/urandom | xxd -p) && mkdir -p "$PWD/.turbo/oracle" && echo "$PWD/.turbo/oracle/$ORACLE_TAG.txt"

Substitute the printed value for <printed-path> in the command below and on every follow-up turn. Shell variables do not survive between shell calls, and an earlier cd in a compound command leaves the session in a different directory, so a relative path resolves against that directory instead.

python3 scripts/run_oracle.py --prompt "<problem description>" --file <relevant files...> --write-output "<printed-path>"

Keep backticks, $, and straight double quotes out of --prompt even in text you wrote: the first two stay live inside the quotes, and a double quote ends them. Text you did not author — a diff, file contents, an error trace, command output — goes in a file passed with --file, written with apply_patch, as does any title or passage the prompt would otherwise quote. This holds on follow-up turns too.

If the run fails, retry the command once — same prompt, attachments, and timeout — when the failure looks transient, such as a browser challenge or automation error while the signed-in session is otherwise healthy. Report an authentication, browser-challenge, or permission blocker only after the retry reproduces it, and cite the failing output. Do not broaden permissions when the current context already has the access the run needs.

Step 4: Follow Up

Resume the same ChatGPT conversation with --followup and the session slug. The prior turn's attached files and context persist, so re-attaching the full diff each turn is unnecessary. Use the same generous timeout as Step 3 (60 minutes / 3600000ms):

python3 scripts/run_oracle.py --followup "<session-slug>" --prompt "<follow-up>" --write-output "<printed-path>"

Find the slug with python3 scripts/run_oracle.py status (the Slug column; follow-ups nest under their parent session) or from the directory names under ~/.oracle/sessions/.

Reuse the chat for a multi-turn review of the same code; start a fresh session (Step 3) for an unrelated question. Cap at 5 turns to prevent runaway conversations.

When the reviewed code changed since the prior turn, re-attach the changed files (--file <paths>) or a fresh diff, or state what changed. Otherwise the model reasons from the earlier attachments and flags already-fixed issues as live contradictions.

Step 5: Synthesize

Read the response from <printed-path>. Summarize the key insights from the consultation. Cross-reference suggestions with official docs and peer open-source implementations before applying. Oracle suggestions are starting points, not guaranteed solutions.

Then call update_plan to mark this step completed and continue with the next step of the active workflow.