---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-context-packing-reference"
title: "Context packing with Oracle and PackX: practical reference"
---

# Context packing with Oracle and PackX: practical reference

## Agent Setup Prompt

```text
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:

```text
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:

```text
skills/oracle-packx/SKILL.md
```

Supporting references:

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

A common local install path is:

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

Oracle project reference:

```text
https://github.com/johnlindquist/oracle
```

PackX package and reference:

```text
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:

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

What this workflow gives you now:

```text
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:

```text
oracle
oracle-mcp
```

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

Useful project files to inspect:

```text
~/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:

```text
~/.oracle/sessions/{slug}/
```

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

```text
~/.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:

```text
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:

```text
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:

```text
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:

```json
{
  "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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```markdown
# 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:

```text
- 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

```text
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
```

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
