Oracle handoff for a huge codebase question playbook

Working web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.

Original source pages and recordings require authorized access. The full article text here is public.

Working web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.

Core principles

Copy-paste workflow

When to use: When a read-heavy question spans a large codebase and would burn your Codex token/rate budget. Offload the heavy analysis to a browser ChatGPT Pro Extended Thinking session via Oracle + PackX, then bring the returned plan back into Codex and implement locally.

Copy-paste prompt

You are my coding agent. I have a large, read-heavy question about this codebase and I want to offload the heavy analysis to a browser ChatGPT Pro session via Oracle + PackX instead of burning local tokens. Follow these steps exactly and do not skip the preview.

1. Bundle the relevant files with PackX. First PREVIEW so we see what gets included and the token estimate:
     packx --preview -s "<TOPIC>"
   When the preview looks right, write the bundle:
     packx -s "<TOPIC>" -f markdown --no-interactive -o .notes/handoff-bundle.md

2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words:
     ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \
       -p "<THE BIG ANALYSIS QUESTION>" \
       --slug "<3-5-word-kebab-slug>" \
       --write-output .notes/oracle-plan.md \
       --file .notes/handoff-bundle.md

3. Read .notes/oracle-plan.md, then implement the plan locally and verify (run the tests/build). Treat this as a plan -> implement -> verify loop.

Guardrail: keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.

How it works

  • packx --preview -s "<TOPIC>" shows the matched files and a token estimate before you commit — always preview first so the bundle is scoped, not bloated.
  • packx -s "<TOPIC>" -f markdown --no-interactive -o .notes/handoff-bundle.md writes a scripted markdown bundle (no prompts).
  • oracle --engine browser --browser-thinking-time extended drives ChatGPT Pro in the browser with extended thinking; --write-output saves ONLY the final assistant message, and --file attaches the bundle (cap raised via ORACLE_MAX_FILE_SIZE_BYTES=12000000).
  • The --slug must be 3-5 kebab words or Oracle rejects it.
  • The returned plan is the durable artifact: read it back into Codex, implement, then verify. Keep concurrency low (2-3 browser requests) to stay within ChatGPT Pro limits.
  • Reference: John's Oracle fork, PackX.

Reusable skill

Install as ~/.agents/skills/oracle-codebase-handoff/SKILL.md, then restart Codex.

---
name: oracle-codebase-handoff
description: Trigger when a read-heavy question spans a large codebase and would burn Codex token/rate budget — offload heavy analysis to a browser ChatGPT Pro session via Oracle + PackX, then resume implementation locally. Do NOT trigger for small, local edits.
---

# Oracle codebase handoff

Offload a big, read-heavy codebase analysis to a browser ChatGPT Pro session via Oracle + PackX, then bring the plan back and implement locally. Run as a plan -> implement -> verify loop.

## Steps

1. Bundle the relevant files with PackX. PREVIEW first to confirm scope and token estimate, then write the bundle:
   ```bash
   packx --preview -s "<topic>"
   packx -s "<topic>" -f markdown --no-interactive -o .notes/handoff-bundle.md
   ```
   `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first; use `--no-interactive` for scripted bundles.

2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words, and the prompt text must start with `[<slug>]` on line 1, a blank line, then the question:
   ```bash
   ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \
     -p "[<3-5-word-kebab-slug>]\n\n<the big analysis question>" \
     --slug "<3-5-word-kebab-slug>" \
     --write-output .notes/oracle-plan.md \
     --file .notes/handoff-bundle.md
   ```
   - `--engine browser` automates ChatGPT in the browser (GPT models).
   - `--browser-thinking-time extended` sets ChatGPT thinking time (light|standard|extended|heavy).
   - `--write-output` writes ONLY the final assistant message.
   - `--file` attaches the bundle (size cap raised via `ORACLE_MAX_FILE_SIZE_BYTES`).

3. Read `.notes/oracle-plan.md`, then implement the plan locally and verify (tests/build).

## Guardrails
- Slug MUST be 3-5 kebab words or Oracle rejects it.
- Keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.
- Do NOT use this for small, local edits — only for read-heavy, large-codebase questions.

Scenarios

Unblock a tangled Next.js auth redirect bug

Role: As a senior full-stack web developer owning a Next.js app

A production-like local Next.js app has a login redirect loop that only appears after mixing middleware, server components, API route auth checks, and client-side session refresh. The issue spans many files, so asking Codex to read everything directly would burn the interactive session budget.

As a senior full-stack web developer, I want Codex to offload the broad auth-flow investigation through Oracle and PackX, so that Codex can spend its local context on implementing and verifying the fix instead of reading the whole repo.

Agent brief

You are my coding agent in this repo. Investigate the auth redirect loop by using the Oracle codebase handoff workflow, then implement only the locally verifiable fix. Do not skip the PackX preview. Create `.notes/` if needed. First run `packx --preview -s "Next.js auth redirect middleware session login callback API route"` and inspect the matched files and token estimate. If the scope is reasonable, run `packx -s "Next.js auth redirect middleware session login callback API route" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then send the bundle through Oracle browser mode with a 3-5 word kebab slug, and make the prompt start with the same bracketed slug on line 1: `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[auth-redirect-loop]\n\nWe have a Next.js auth redirect loop. Read the attached PackX bundle and produce: 1) the likely root cause, 2) the exact files/functions to inspect first, 3) a minimal implementation plan, 4) local verification steps using the dev server/browser, and 5) risks or false leads to avoid. Do not propose unrelated rewrites." --slug "auth-redirect-loop" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, read `.notes/oracle-plan.md`, summarize the recommended fix in `.notes/auth-redirect-receipt.md`, implement the smallest safe change, then run the repo's existing typecheck/test/build command discovered from package scripts. Finally start the local dev server and verify the login flow in a browser.

Implementation references

Open reference

Open reference

Open reference

packx --preview -s "Next.js auth redirect middleware session login callback API route"
packx -s "Next.js auth redirect middleware session login callback API route" -f markdown --no-interactive -o .notes/handoff-bundle.md
ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[auth-redirect-loop]\n\n<question>" --slug "auth-redirect-loop" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md

Browser verification

Use the running local app as proof, not source-code confidence. In a CMUX browser pane or browser-agent workflow, open the dev server, capture an accessibility snapshot of the login page, click the sign-in control, fill the test credentials or scripted local auth fields, submit, and evaluate window.location.pathname plus visible authenticated UI text. Save a screenshot or browser transcript showing the flow reaches the expected post-login route without bouncing back to /login.

Definition of done

  • .notes/oracle-plan.md exists and contains the browser-side Oracle recommendation
  • .notes/auth-redirect-receipt.md records the selected fix, files changed, and why alternatives were rejected
  • Repo verification command passes, such as test/typecheck/build from package scripts
  • Browser proof shows login reaches the expected authenticated route without a redirect loop
  • Git diff is limited to the auth-related fix and does not include .notes/ artifacts

Failure modes and mitigations

  • Mistake: using Oracle before previewing the bundle, causing a bloated or irrelevant handoff. Mitigation: require packx --preview first and adjust the search topic before writing .notes/handoff-bundle.md.
  • Mistake: implementing the whole Oracle plan as if it were guaranteed correct. Mitigation: treat .notes/oracle-plan.md as a plan, then implement the smallest locally verifiable change and prove it in the browser.
  • Mistake: using a slug that Oracle rejects. Mitigation: use exactly 3-5 kebab words and start the prompt with [same-slug] followed by a blank line.
  • Mistake: trusting unit tests for a browser-only redirect bug. Mitigation: require browser proof against the running dev server.

Find the real owner of a checkout state bug

Role: As a product engineer maintaining a checkout funnel

A React or Remix checkout page loses cart state when the user changes shipping method, navigates back, or refreshes after payment intent creation. The logic is split across route loaders/actions, client state, server API handlers, and payment integration code.

As a product engineer, I want a huge-context Oracle pass to map the checkout state ownership and failure points, so that my local agent can make a targeted fix and prove the checkout flow in the browser.

Agent brief

You are my coding agent. Use Oracle + PackX only for the broad read-heavy diagnosis, then return to local implementation and verification. Create `.notes/` if needed. Run `packx --preview -s "checkout cart state shipping method payment intent loader action API"`. Review the preview for checkout routes, cart/session modules, API handlers, and payment-related files. If relevant, run `packx -s "checkout cart state shipping method payment intent loader action API" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[checkout-state-owner]\n\nRead the attached checkout-related codebase bundle. Identify which layer should own checkout/cart state, where the current flow can lose state during shipping changes, browser back navigation, refresh, or payment intent creation, and propose the smallest fix. Return exact file/function references, a step-by-step implementation plan, and browser verification steps. Avoid broad architecture rewrites unless the current code makes a minimal fix unsafe." --slug "checkout-state-owner" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. Read the returned plan, write `.notes/checkout-handoff-receipt.md` with the chosen path, implement the minimal fix, then run existing tests/build. If the repo has no browser test, use the dev server plus a browser-agent or CMUX browser pane to verify the funnel manually and record evidence.

Implementation references

Open reference

Open reference

Open reference

packx --preview -s "checkout cart state shipping method payment intent loader action API"
packx -s "checkout cart state shipping method payment intent loader action API" -f markdown --no-interactive -o .notes/handoff-bundle.md
ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[checkout-state-owner]\n\n<question>" --slug "checkout-state-owner" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md

Browser verification

Use browser verification because this bug is about real user navigation. In the local app, open the checkout route, capture a snapshot of cart line items and total, click through shipping method changes, use back/forward navigation, refresh once after the payment-intent step if safe in the local/test environment, and evaluate the visible cart total plus any checkout state exposed in the page. Save a screenshot or transcript proving the cart survives the exact sequence.

Definition of done

  • PackX preview was inspected before bundle creation
  • .notes/oracle-plan.md contains a file/function-level checkout state diagnosis
  • .notes/checkout-handoff-receipt.md names the selected minimal fix and verification sequence
  • Existing repo checks pass
  • Browser proof shows the checkout state survives shipping change, back navigation, and refresh in the local/test flow

Failure modes and mitigations

  • Mistake: asking Oracle for a generic checkout redesign. Mitigation: phrase the Oracle prompt around state ownership, exact failure paths, minimal fix, and browser proof.
  • Mistake: including live secrets, customer data, or real payment credentials in logs or screenshots. Mitigation: use local/test data only and redact artifacts before saving.
  • Mistake: letting Codex use Oracle for every small follow-up. Mitigation: use Oracle once for the broad read-heavy map, then continue locally unless another huge-codebase question appears.
  • Mistake: verifying only the happy path. Mitigation: require the back/refresh/shipping-change sequence that reproduced the bug.

Map a legacy migration before touching code

Role: As a tech lead planning a risky front-end migration

A large web app is moving one feature area from legacy pages to a newer app-router or component architecture. The team needs to know which files, routes, shared utilities, and tests are involved before assigning implementation work.

As a tech lead, I want an Oracle handoff to produce a migration map from the current codebase, so that the implementation agent can work from a grounded plan and avoid guessing across many files.

Agent brief

You are my coding agent. This is a read-heavy migration-mapping task, so use Oracle handoff first and do not edit source files until the returned plan is reviewed. Create `.notes/` if needed. Run `packx --preview -s "legacy feature migration routes components shared utilities tests"`. If the preview includes the expected legacy feature area, run `packx -s "legacy feature migration routes components shared utilities tests" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[legacy-migration-map]\n\nRead the attached PackX bundle for a large web app migration. Produce an implementation-ready migration map: current entry points, route/page ownership, shared components/utilities, test/build commands to run, risky coupling points, safe first slice, and a plan -> implement -> verify sequence. Do not invent tools or recommend a broad rewrite; stay grounded in the attached code." --slug "legacy-migration-map" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, create `.notes/migration-slice-receipt.md` with the first safe slice, explicit files to edit, verification commands, and browser proof needed. Implement only that first slice if it is small enough; otherwise stop with the migration map and receipt for human review.

Implementation references

Open reference

Open reference

Open reference

Open reference

packx --preview -s "legacy feature migration routes components shared utilities tests"
packx -s "legacy feature migration routes components shared utilities tests" -f markdown --no-interactive -o .notes/handoff-bundle.md
ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[legacy-migration-map]\n\n<question>" --slug "legacy-migration-map" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md

Browser verification

Browser proof is useful only after a concrete migration slice exists. For the planning-only phase, the right proof is .notes/oracle-plan.md plus a migration receipt. If implementing the first slice, open old and new routes in a local browser or CMUX browser pane, capture snapshots/screenshots of the same user-visible state, click the primary controls, and confirm the migrated route preserves the expected behavior.

Definition of done

  • .notes/oracle-plan.md exists and maps entry points, route ownership, shared utilities, risks, and first safe slice
  • .notes/migration-slice-receipt.md converts the Oracle recommendation into a local implementation decision
  • No source files are changed unless the first slice is explicitly small and verifiable
  • If a slice is implemented, existing checks pass and browser comparison proof exists for old versus new route behavior
  • The final review artifact names what remains out of scope

Failure modes and mitigations

  • Mistake: turning a migration map into a giant unreviewed rewrite. Mitigation: require a first safe slice and stop for review if the change is not small and verifiable.
  • Mistake: packing the entire repo without topic discipline. Mitigation: preview with a migration-specific search phrase and narrow before writing the bundle.
  • Mistake: treating Oracle's output as fresh repo truth after code changes. Mitigation: once implementation begins, inspect current files locally and verify against the running app.
  • Mistake: using browser proof too early. Mitigation: use browser proof after a concrete UI slice exists; use the Oracle plan and receipt as planning proof before edits.

Implementation notes

  • Use Oracle only for read-heavy, large-codebase analysis. Small local edits should stay in Codex without the browser handoff.
  • Always preview PackX output before writing .notes/handoff-bundle.md; the preview is the quality gate for scope and token cost.
  • The Oracle slug must be 3-5 kebab words, and the prompt must start with [same-slug], then a blank line, then the question.
  • Keep browser concurrency low: no more than two or three Oracle browser requests at once.
  • Treat .notes/oracle-plan.md as a planning artifact, not a commandment. The local agent still has to inspect current files, implement the smallest safe slice, and verify with tests/build/browser proof.
  • Keep .notes/ artifacts local working files. Do not commit Oracle bundles or plans unless the repo deliberately wants them.
  • For browser proof, prefer user-visible receipts: screenshot, accessibility snapshot, console-free run, route/path evaluation, or a short transcript of click/fill/evaluate steps.
  • Do not put secrets, customer data, real payment credentials, or private cookies into PackX bundles, logs, browser screenshots, or .notes/ receipts.

Boundaries and caveats

  • Do not introduce NotebookLM as part of this Oracle workflow; it was not retained as a taught workflow for this topic.
  • Do not add a generic API/manual-copy lane as if it were taught here; keep the workflow centered on Oracle + PackX + browser handoff.
  • Do not claim browser-side work is permanently unlimited, free, or policy-proof. Frame quota behavior as the workshop setup and keep concurrency conservative.
  • Do not use Oracle to bypass normal local verification. The final proof still comes from tests, build logs, and the running web app.
  • Do not invent unverified CMUX, PackX, or Oracle flags. Use the verified command shapes in the command reference.

Agent reference map

Oracle codebase handoff prompt

Use this as the copy-paste workflow shape for PackX preview, PackX bundle creation, Oracle browser handoff, returned-plan file, and local verification loop.

Open reference

Oracle codebase handoff Codex skill

Use this when the local agent needs the strict runnable version: preview first, slug rules, prompt prefix, --write-output, --file, and plan -> implement -> verify.

Open reference

Verified Oracle + PackX command surface

Use this to avoid inventing flags. It includes the verified oracle --engine browser --browser-thinking-time extended command, ORACLE_MAX_FILE_SIZE_BYTES, PackX preview/write commands, token-limit notes, and slug rules.

Open reference

Lesson 01 validated references

Use this as the taught-source boundary for the Oracle topic: Codex-to-browser quota offloading, ChatGPT Pro Extended as a high-context browser surface, PackX context bundling, MCP/browser bridge, low concurrency, and plan -> implement -> verify.

Open reference

PackX preview command

Run before writing any bundle so the agent can check matched files and token estimate instead of blindly sending irrelevant context.

packx --preview -s "<TOPIC>"

PackX bundle command

Write the relevant codebase context into a model-readable markdown file that Oracle can attach.

packx -s "<TOPIC>" -f markdown --no-interactive -o .notes/handoff-bundle.md

Oracle browser handoff command

Send the PackX bundle to browser ChatGPT with extended thinking and save only the final assistant message to a local plan file.

ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p "[<3-5-word-kebab-slug>]\n\n<the big analysis question>" --slug "<3-5-word-kebab-slug>" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md

CMUX browser/local verification surface

Use a browser pane or browser-agent-style workflow to prove web app behavior after local implementation, especially login, checkout, navigation, and route migration flows.

cmux --json tree; cmux read-screen; local dev server URL from repo package scripts

Command reference

These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.

Oracle CLI (browser handoff) — verified flags

ORACLE_MAX_FILE_SIZE_BYTES=12000000 \
oracle --engine browser --browser-thinking-time extended \
  -p "[<3-5-word-kebab-slug>]\n\n<the big analysis question>" \
  --slug "<3-5-word-kebab-slug>" \
  --write-output .notes/oracle-plan.md \
  --file .notes/handoff-bundle.md

Verified options (from oracle --help and the Oracle source):

  • --engine browser — automate ChatGPT in the browser (GPT models). Default picks api when OPENAI_API_KEY set, else browser.
  • --browser-thinking-time <light|standard|extended|heavy> — ChatGPT thinking time (source: src/cli/browserConfig.ts, src/mcp/types.ts).
  • --write-output <path> — write ONLY the final assistant message to a file.
  • --slug "<words>" — session slug, MUST be 3-5 words.
  • --file <paths...> — attach files/dirs/globs (cap configurable via ORACLE_MAX_FILE_SIZE_BYTES).
  • --browser-attachments <auto|never|always>, --browser-bundle-files — control upload behavior.

Slug rule (validated): 3-5 kebab words. The oracle prompt text MUST start with [<slug>] on line 1, blank line, then the prompt.

PackX (context bundling) — verified flags from packx --help

packx --preview -s "<TOPIC>"                                   # preview matching files + token estimate FIRST
packx -s "<TOPIC>" -f markdown --no-interactive -o .notes/handoff-bundle.md
packx <PATH> -i "*.ts" --no-interactive -o bundle.md          # positional path + glob include
packx --diff -f markdown --no-interactive -o bundle.md         # only files changed from main
packx --staged ...  | --dirty ...                              # staged-only / modified+untracked
packx FILTERS --limit 900k -f markdown --no-interactive -o bundle.md   # token budget
packx FILTERS --strip-comments --minify ...                    # compressed bundle
packx FILTERS -M 32k                                           # split into chunks
packx --no-packignore <DOTFILE_PATH>                           # include dotfiles / ignored paths

Key rules: -i is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always --preview first. Use --no-interactive for scripted bundles. Formats: xml (default), markdown, plain, jsonl.

MCP equivalent

mcp__oracle__consult with engine: "browser", slug, browserThinkingTime: "extended", files, browserAttachments. The packx bundle goes in ~/.oracle/bundles/{slug}.txt; output in ~/.oracle/sessions/{slug}/output.log. Browser-mode bundle target up to ~900k tokens. Keep concurrency low (2-3 browser requests max).

Source references