Context packing with Oracle and PackX: practical reference

Documents the oracle-packx workflow: setup and verification prompts, bounded context selection, PackX preview and bundling, Oracle CLI/MCP browser execution, optional Tailscale routing, privacy exclusions, compact evidence, session-output review,…

Agent Setup Prompt

Set up the oracle-packx skill, PackX bundle flow, Oracle browser runtime, MCP entrypoints, optional remote browser route, and local verification surfaces for this workspace.

1. Resolve the oracle-packx skill. Check `skills/oracle-packx/SKILL.md` first, then `~/.agents/skills/oracle-packx/SKILL.md`. Confirm the PackX references exist under `skills/oracle-packx/references/` or the matching installed skill path. Read the skill before changing config. If the skill is missing, report the missing path and the smallest install or copy step needed; do not invent skill content.

2. Verify PackX availability. Run `command -v packx || npx packx --help`. Confirm a preview command is available before building anything. Do not create a broad bundle during setup.

3. Verify Oracle entrypoints. Run `command -v oracle oracle-mcp` and report both results. If either command is missing, inspect `~/dev/oracle/docs/configuration.md`, `~/dev/oracle/docs/mcp.md`, `~/dev/oracle/docs/browser-mode.md`, and `~/dev/oracle/docs/bridge.md` if present, then report the exact missing install or PATH step.

4. Prepare local artifact directories. Confirm `~/.oracle/`, `~/.oracle/bundles/`, and `~/.oracle/sessions/` exist. Create only missing directories. Do not delete, overwrite, or rename existing sessions or bundles.

5. Configure Oracle for deliberate browser mode. Inspect `~/.oracle/config.json` if it exists, preserving existing private values. Ensure this workflow resolves to `engine: "browser"`, with browser thinking set to extended, model label set to Latest, browser attachments set to always, browser file bundling enabled, and `maxFileSizeBytes` set to a reasonable upload guardrail such as `10485760`. Do not clobber unrelated config.

6. Verify MCP/browser request fields. Confirm a setup run would pass or resolve these values: `engine: "browser"`, `browserThinkingTime: "extended"`, `browserModelLabel: "Latest"`, `browserAttachments: "always"`, and `browserBundleFiles: true`. Flag any condition where Oracle would fall back to API mode.

7. Optional remote browser route. If remote browser routing is intended, verify the config shape without exposing values: `browser.remoteHost` should look like a Tailscale host and port, `browser.remoteToken` should be present but redacted, and `browser.remoteChrome.host` plus `browser.remoteChrome.port` should point at the remote Chrome debug bridge from the remote server's perspective. If no remote route is configured, report it as skipped.

8. Enforce privacy boundaries. Never print or bundle tokens, cookies, API keys, private endpoints, raw `env` output, full private config, huge logs, generated output, `node_modules/`, `.git/`, build output, coverage output, or unrelated product areas. Confirm `CLAUDE.md` is excluded from Oracle PackX bundles. Use compact redacted notes when evidence is useful but unsafe or too large.

9. Verify the PackX context flow with a tiny dry run. From a safe local project path, run a preview against a narrow path or harmless file set using the skill's PackX reference. Report file count, token count if available, and whether the scope would produce a non-empty bundle. Do not upload files to Oracle during this preview.

10. Verify bundle and session surfaces. Using a short setup slug, confirm a bundle path like `~/.oracle/bundles/{slug}.txt` can be written and is non-empty if you build a tiny safe bundle. Confirm a session directory path like `~/.oracle/sessions/{slug}/` can exist, and that the expected post-run output file is `~/.oracle/sessions/{slug}/output.log`.

11. If a live browser Oracle smoke test is safe and explicitly allowed by the local environment, run only a minimal browser-mode check with harmless content. Otherwise stop before sending anything and report the remaining manual check: signed-in browser availability, remote host reachability if used, and expected `output.log` location.

12. Report the setup result plainly: skill path resolved, PackX status, Oracle CLI status, Oracle MCP status, directories present or created, browser-mode config status, resolved engine, remote route configured or skipped, preview result, bundle/session surface status, verification commands run, files created or changed, and anything still unproven. Redact all secrets and do not paste full config.

Big Idea

Phase: Context And Environment - make the software question, project boundary, and model runtime explicit before deeper work begins.

Use the oracle-packx skill when a software question needs more context than a normal chat turn can hold, or when the answer should come from a stronger browser-backed model with a deliberate context packet.

Try This Now

Pick one risky software question, such as "Why can this billing webhook double-process an invoice?"

Write one sentence for each boundary:

  • in scope: likely source files, tests, logs, docs, screenshots, or prior notes
  • out of scope: generated output, secrets, unrelated product areas, broad history
  • useful answer: plan, bug theory, file-level review, first slice, or verification target

Ask:

Use the oracle-packx skill.

Build a bounded PackX bundle before recommending a fix. Use Oracle through
browser mode. Read the full Oracle output from the local session log before
turning it into project work.

Skill Reference

The repeatable workflow lives in the bundled skill:

skills/oracle-packx/SKILL.md

Supporting references:

skills/oracle-packx/references/packx-quick-reference.md
skills/oracle-packx/references/packx-deep-reference.md

A common local install path is:

~/.agents/skills/oracle-packx/SKILL.md

Oracle project reference:

https://github.com/johnlindquist/oracle

PackX package and reference:

https://www.npmjs.com/package/packx
https://github.com/johnlindquist/pack#readme

When To Reach For This

Use oracle-packx when you are asking for:

  • architecture review across several files or packages
  • an implementation plan for a feature with real source context
  • cross-file debugging where the failure path spans source, tests, logs, and config
  • a second opinion before touching a risky subsystem
  • review of a failed implementation after you have logs or test output
  • a broad code review where local inspection alone is not enough
  • a browser-backed Oracle run that should use a signed-in ChatGPT/Gemini session instead of a normal API call

Skip it when:

  • rg can answer the question
  • one test failure points at one obvious file
  • you already know the exact edit
  • the task is small enough for a normal Codex turn

How This Used To Work

What you used to expect:

Paste a broad prompt and trust the model to infer the right files.

What this workflow gives you now:

Give oracle-packx a specific software question. It builds a bounded context
packet first, then Oracle reasons over the code, docs, logs, and evidence that
actually matter.

Mental Model

There are three pieces:

Piece Job
oracle-packx Workflow wrapper: choose scope, preview PackX, build the bundle, call Oracle, read the result, apply it locally
PackX Context bundler: collect, filter, count, and write source context into an LLM-friendly packet
Oracle Model runner: CLI/MCP tool that can use API mode or browser mode, then save session output locally

Do not blur those together. PackX prepares the context. Oracle reasons over it. The agent still owns local edits and verification.

Oracle Runtime Setup

Oracle can run from the CLI or from the MCP tool.

Common entrypoints:

oracle
oracle-mcp

The project includes browser-mode code, MCP tools, remote-browser routing, session storage, and launch helpers.

Useful project files to inspect:

~/dev/oracle/docs/browser-mode.md
~/dev/oracle/docs/configuration.md
~/dev/oracle/docs/mcp.md
~/dev/oracle/docs/bridge.md
~/dev/oracle/src/mcp/server.ts
~/dev/oracle/src/mcp/tools/consult.ts
~/dev/oracle/src/mcp/tools/sessions.ts
~/dev/oracle/src/mcp/tools/sessionResources.ts
~/dev/oracle/src/config.ts
~/dev/oracle/src/remote/client.ts
~/dev/oracle/src/remote/server.ts
~/dev/oracle/src/browser/index.ts
~/dev/oracle/scripts/oracle-serve-launchagent.sh

Oracle session output is saved under:

~/.oracle/sessions/{slug}/

For oracle-packx, the main file to read after the run is normally:

~/.oracle/sessions/{slug}/output.log

Browser Mode

Browser mode sends the request through an automated signed-in browser session instead of the normal API path.

Use it when the answer should come from ChatGPT/Gemini web capabilities, attached files, a visible remote browser, or a browser-only model surface.

Critical MCP fields:

engine: "browser"
browserThinkingTime: "extended"
browserModelLabel: "Latest"

Why engine: "browser" matters:

  • Oracle can choose a default engine from config.
  • If API credentials exist, API mode may be available.
  • A deliberate browser run should not accidentally become an API run.

Browser attachment controls:

browserAttachments: "always"
browserBundleFiles: true

Use browserAttachments: "always" when files must be uploaded through the browser UI. Use bundling when many files should travel as one uploaded context artifact.

Remote Oracle Browser Path

A common remote setup uses a Tailscale-reachable Oracle browser host. This lets the local agent send the job while the remote machine drives an already signed-in browser session, often visible on a TV or second display.

The path looks like this:

local Codex / agent
  -> Oracle MCP consult or oracle CLI
  -> browser engine
  -> browser.remoteHost over Tailscale
  -> remote oracle serve process
  -> remoteChrome on the remote host
  -> signed-in ChatGPT/Gemini browser
  -> local ~/.oracle/sessions/{slug}/ output

Redacted config shape:

{
  "engine": "browser",
  "browser": {
    "remoteHost": "100.x.y.z:7333",
    "remoteToken": "<redacted>",
    "remoteChrome": {
      "host": "127.0.0.1",
      "port": 55894
    }
  },
  "maxFileSizeBytes": 10485760
}

What each field means:

Field Meaning
engine Default Oracle runtime mode
browser.remoteHost Tailscale-reachable Oracle remote server
browser.remoteToken Bearer-style token required by the remote server
browser.remoteChrome.host Chrome debugging host from the remote server's point of view
browser.remoteChrome.port Chrome debugging port on the remote machine
maxFileSizeBytes Local upload guardrail for files sent to browser mode

The token is private. Do not paste it into prompts, bundles, pages, logs, or screenshots.

Ask The Agent This

General review:

Use the oracle-packx skill.

Review the auth/session architecture before we add refresh-token rotation.
Build a focused PackX bundle from the auth package, session storage code,
middleware, relevant tests, and existing ADRs. Exclude secrets, generated
output, node_modules, and unrelated product areas.

Ask Oracle through browser mode for risks, a migration plan, file-level changes,
verification checks, rollback notes, and the first shippable slice. Read the
full Oracle session output before editing local files.

Debugging:

Use the oracle-packx skill.

The billing webhook intermittently double-processes an invoice. Bundle the
webhook handler, idempotency code, tests, payment-provider docs, and the latest
failure log. Ask Oracle through browser mode to identify likely causes, missing
invariants, and the smallest local check that would confirm the fix.

Remote browser setup check:

Use the oracle-packx skill.

Inspect the local Oracle config and explain whether browser mode will route to a
remote Tailscale Oracle host. Redact tokens and private host details. Confirm the
engine choice, remoteHost shape, remoteChrome target, file-size guardrail, and
where the session output will be saved.

Keep the bundle tight:

Use the oracle-packx skill.

Start with a PackX preview. If the bundle is too broad, narrow by package,
entrypoint, git diff, or relevant search terms before consulting Oracle. Do not
send secrets, generated files, private env output, or raw huge logs.

What The Skill Does

The oracle-packx skill runs this pipeline:

  1. Choose a short slug.
  2. Preview the PackX bundle before building it.
  3. Build a rich bundle, often targeting up to 900k tokens for broad review.
  4. Confirm the bundle exists and is non-empty.
  5. Add compact evidence when raw logs or sessions are too large or unsafe.
  6. Send the bundle to Oracle through browser mode only.
  7. Use ChatGPT Pro Extended or equivalent browser thinking controls.
  8. Wait for Oracle instead of doing parallel local work.
  9. Read the full answer from ~/.oracle/sessions/{slug}/output.log.
  10. Turn Oracle's answer into local implementation work.
  11. Write local plans, notes, code, or verification logs with local tools.

What PackX Is Doing

PackX discovers files, applies ignore rules, filters by path/content/git state, optionally strips comments or minifies, counts tokens, and writes an LLM-friendly bundle.

Common PackX capabilities used by the skill:

Capability What It Means
--preview Dry run before building the bundle
--limit 900k Rich bundle target for broad Oracle review
-x / --exclude Leave out noise or unsafe files
-i / --include Include specific path/glob patterns
-s / --strings Find files containing relevant text
--diff / --dirty / --staged Focus on changed files
--follow-imports Start from an entrypoint and include local imports
--skeleton Send API/interface shape without full bodies
--strip-comments --minify Fit large projects into the bundle
-f markdown --no-interactive --stdout Scriptable output shape for Oracle

Use these flags conceptually. The exact combinations live in the skill and quick reference.

What To Exclude

The skill explicitly excludes CLAUDE.md from Oracle PackX bundles.

Why:

  • it may contain tool-specific or agent-specific instructions
  • it can confuse the Oracle review with instruction noise
  • repo guidance should be deliberately scoped

Prefer a scoped AGENTS.md, project README, ADR, or short local summary when instructions are needed.

Also keep these out unless there is a deliberate reason:

node_modules/
.git/
dist/
build/
.next/
coverage/
*.log
lockfiles
raw env output
tokens
cookies
private endpoints

Logs can still be included intentionally when they are small and directly relevant. Large logs should usually become compact evidence.

Compact Evidence

Use compact evidence when the raw material is useful but too noisy, too large, or unsafe to bundle directly.

Examples:

  • a giant failure log
  • previous session history
  • screenshot observations
  • browser trace summary
  • CI output with many unrelated lines
  • a redacted production incident note
  • redacted Oracle config details
  • a failed PackX preview that proved the first scope was too broad

Shape:

# Compact Evidence Supplement

## Useful Facts

- fact:
- source path:
- why it matters:

## Raw Context Intentionally Omitted

- path:
- omitted because:

## Current Narrowing

- next slice:
- out of scope:
- how to confirm:

How To Know It Worked

After the skill runs, look for:

  • a non-empty bundle at ~/.oracle/bundles/{slug}.txt
  • an Oracle session at ~/.oracle/sessions/{slug}/
  • a full session output file, normally output.log
  • browser mode noted in the run, not accidental API mode
  • remote-browser routing redacted when config is discussed
  • exact file/function/test targets in the plan
  • risks and assumptions called out explicitly
  • a first shippable slice, not just a broad roadmap
  • local files written by the agent, not downloadable files created by Oracle

If It Goes Wrong

Symptom Likely Cause What To Do
Oracle used API mode engine: "browser" was omitted or config default changed Re-run with explicit browser engine
Browser did not open Browser automation or remote host is unavailable Check local Oracle config and browser-mode docs
Remote host unreachable Tailscale, host, port, or remote server is down Confirm the 100.x.y.z:port route and remote oracle serve process
Token rejected Remote token mismatch Rotate or fix the token outside the bundle and prompt
Remote Chrome unavailable Debug port or Chrome session is not running on the remote host Restart the remote Chrome/debug bridge or launch helper
File upload rejected Bundle or attachment exceeded guardrails Narrow PackX scope, use compact evidence, or bundle fewer files
Bundle is huge Scope was too broad Preview again with tighter includes, excludes, strings, diff, or entrypoints
Bundle is empty Include patterns missed the actual files Run rg, inspect paths, and rebuild
Oracle answer is vague Context packet lacked logs, tests, or target question Add compact evidence and ask for a falsifiable first check
Sensitive data appears Secrets or raw env output slipped in Stop, remove the bundle, rebuild with redaction

Follow-Up Rules

Oracle's answer is input, not the finished work.

After reading it:

  • restate the useful recommendation in local project terms
  • identify the first file or test to touch
  • keep unrelated refactors out
  • run the smallest meaningful verification
  • save what changed and what remains unproven
  • use another PackX/Oracle pass only after forward progress or new evidence

When returning to Oracle, include the delta:

- prior_oracle_session:
- last_oracle_recommendation:
- implemented_since_prior_oracle:
- verified_since_prior_oracle:
- failed_check_or_blocker:
- narrowing_decision:
- files_functions_now_in_scope:
- files_functions_out_of_scope:
- next_falsifiable_verification:

References And Resources

skills/oracle-packx/SKILL.md
skills/oracle-packx/references/packx-quick-reference.md
skills/oracle-packx/references/packx-deep-reference.md
~/dev/oracle/docs/browser-mode.md
~/dev/oracle/docs/configuration.md
~/dev/oracle/docs/mcp.md
~/dev/oracle/docs/bridge.md
~/.oracle/config.json
~/.oracle/bundles/{slug}.txt
~/.oracle/sessions/{slug}/output.log

Source references