ChatGPT browser engine

repo-harness chatgpt browser-* drives a locally signed-in ChatGPT Web session for planning and review. It does not use the OpenAI API and does not require OPENAI_API_KEY. Prompts are built from explicit repo files, and every run is saved as a repo-local session record.

The browser engine runs on Oracle — repo-harness wraps oracle --engine browser as the default, recommended provider. The older homegrown Chrome engine is kept only as a deprecated diagnostic.

What it does

Builds policy-checked prompt bundles from explicit files, drives ChatGPT Web through Oracle, and saves session records under .ai/harness/chatgpt/sessions/<sessionId>/.

What it does not do

Never asks for usernames, passwords, SSO secrets, 2FA codes, cookies, or browser tokens. Does not upload arbitrary repo files, does not enable remote CDP by default, and never treats the model reply as the source of truth — the repo-local session store is the audit record.

Provider posture

Oracle is the main path

• oracle — default, recommended. Oracle owns the browser engine; repo-harness always passes --engine browser and disables auto-archive. This is the provider you want.
• native — deprecated. The homegrown Chrome DevTools Protocol engine is no longer maintained and is kept only as a short-term diagnostic (browser-doctor --provider native). It will be removed.

1. First-time setup

1. Create the session root and print recommended ignore rules (browser state stays local):

   repo-harness chatgpt browser-setup --repo .

2. Make a pinned Oracle binary resolvable — on your PATH or in the repo’s node_modules/.bin. Oracle is an optional external CLI with its own runtime requirement (Node ≥ 24), kept separate from repo-harness’s Bun runtime.

3. Verify the engine is ready (this is the authority for the Oracle runtime boundary):

   repo-harness chatgpt browser-doctor --repo . --provider oracle --json

   Rerun until it reports status: "ready". If it reports nodeCompatible: false, fix or reinstall Oracle’s Node runtime first.

Keep browser state out of source control

browser-setup prints ignore rules for local browser profiles and session tokens. Never commit them, and never paste session data into issues, PRs, or shared logs.

2. Dry run

Validate the prompt, file policy, inline size, and session write path without opening ChatGPT. It saves a dry_run session.

repo-harness chatgpt browser-consult \
  --repo . \
  --dry-run \
  --prompt "Review this sprint." \
  --file plans/sprints/example.sprint.md \
  --model "GPT-5 Pro" \
  --thinking heavy

3. Run a consult

Oracle is the default provider, so --provider oracle is optional but shown here for clarity.

repo-harness chatgpt browser-consult \
  --repo . \
  --provider oracle \
  --prompt "Review this PRD and return risks." \
  --file plans/prds/example.prd.md \
  --follow-up "Challenge your previous recommendation." \
  --write-output .ai/harness/handoff/gptpro/chatgpt-review.md

Note

• --model selects the ChatGPT model; --thinking <light|standard|extended|heavy> maps to Oracle’s browser thinking time. Omit --model to keep the model currently selected in the signed-in UI.
• The written answer file is authoritative — stdout/stderr are treated as logs only.
• A clean exit that produces no answer file is reported as recoverable (ORACLE_CAPTURE_INCOMPLETE): the prompt may already be submitted, so reattach with browser-followup rather than re-sending.
• --write-output must be repo-relative and won’t overwrite an existing file unless --overwrite-output is passed; absolute paths need the human-only --allow-absolute-output. Keep GPT Pro outputs under .ai/harness/handoff/gptpro/.

4. Sessions

repo-harness chatgpt browser-list --repo .
repo-harness chatgpt browser-session --repo . chgpt_20260617_120530_review-sprint
repo-harness chatgpt browser-session --repo . chgpt_20260617_120530_review-sprint --metadata-only
repo-harness chatgpt browser-open --repo . chgpt_20260617_120530_review-sprint

Each session is a self-contained record:

• Directory.ai/harness/chatgpt/sessions/

  • Directory<sessionId>/

    • meta.json metadata, timestamps, provider info
    • prompt.md the input prompt
    • transcript.md full conversation
    • output.md captured assistant response
    • events.jsonl structured event stream
    • Directoryartifacts/ optional generated artifacts

      • …

5. Follow-ups & cleanup

Link a follow-up to a saved session — it resumes that conversation through Oracle:

repo-harness chatgpt browser-followup \
  --repo . \
  --session chgpt_20260617_120530_review-sprint \
  --prompt "Turn that review into a Codex-ready goal."

Cleanup defaults to dry-run and only removes candidates when --force is passed:

repo-harness chatgpt browser-cleanup --repo . --status dry_run --limit 20
repo-harness chatgpt browser-cleanup --repo . --status dry_run --limit 20 --force

6. Native provider (deprecated)

Diagnostic only — being removed

The native Chrome DevTools Protocol provider is deprecated. Prefer Oracle. Chrome 136+ also blocks remote-debugging switches against your default Chrome data directory, so any native use requires a non-default --profile-dir.

repo-harness chatgpt browser-doctor --repo . --provider native
repo-harness chatgpt browser-consult --repo . --provider native --prompt "Reply exactly OK"

Native runs use whatever model/thinking is already selected in the ChatGPT Web UI; passing --model or --thinking fails closed. Use Oracle when you need provider-side model selection.

7. Expose via MCP (optional)

Browser tools are disabled in MCP by default. Enable them explicitly:

repo-harness mcp serve \
  --repo . \
  --transport stdio \
  --profile planner \
  --enable-chatgpt-browser

This exposes run_chatgpt_browser_consult, read_chatgpt_browser_session, list_chatgpt_browser_sessions, open_chatgpt_browser_session, and continue_chatgpt_browser_session. MCP consults restrict writeOutput to workflow artifacts such as .ai/harness/handoff/*.md, tasks/reviews/**, .ai/harness/checks/**, plans/prds/**, and plans/sprints/**.

File policy & security

The engine rejects denied files before any browser or provider run, and rejects allowed-path symlinks that resolve outside the repo.

• Allowed by default: AGENTS.md, CLAUDE.md, README.md, docs/**, plans/**, tasks/**, .ai/context/**, .ai/harness/**, package.json
• Denied by default: .env / .env.*, private key and certificate files, .ssh/**, .git/**, node_modules/**, dist/**, build/**, coverage/**, secrets/**, credentials/**, private/**, _ops/**, .repo-harness/**/*.json

Security notes

Keep browser profiles and local config uncommitted. Don’t expose Chrome remote debugging outside localhost without an explicit security plan. Dry-run before sending large or sensitive context, prefer narrow files over whole-repo dumps, and treat generated ChatGPT output as review input — not authoritative code truth.

Next steps

MCP Connector Expose workflow artifacts to ChatGPT and Codex over MCP.

ChatGPT Pro planner The plan-and-review workflow, end to end.