Codex Chatgpt Control

codex-chatgpt-control

Use this skill when a user asks Codex to operate ChatGPT web through a visible browser session, or when a task involves the codex-chatgpt-control SDK.

This skill is for visible, user-directed ChatGPT workflows only. It is not an OpenAI API wrapper, does not call hidden ChatGPT endpoints, and must not bypass login, captcha, product permissions, file permissions, or user confirmation.

Required Posture

1. Prefer the SDK facade from createChatGPT({ agent }).
2. Use ChatGPT web through a compatible Codex/browser bridge. Do not use private ChatGPT network calls.
3. Treat globalThis.agent as host-provided. If it is missing, report a bridge blocker rather than inventing browser state.
4. Stop on login, captcha, rate-limit, selector-drift, upload/download permission, or ambiguous confirmation blockers.
5. Ask for explicit user confirmation before public, destructive, third-party, paid, account-level, or externally visible actions.
6. Redact run reports by default. Raw prompt/response content is opt-in only.
7. Attach only files the user approved.
8. Use official Codex capabilities for local repository editing, commands, tests, branches, and deployment. This SDK controls visible ChatGPT surfaces.
9. When the user requests Chat or Work, call experience.open before configuration or submission. Do not assume the currently visible pane is already the requested experience.

Runtime Requirements

Deterministic local checks need:

• Node.js 20 or newer
• npm
• a source checkout of codex-chatgpt-control

Real browser-control runs also need:

• Chrome with a signed-in visible ChatGPT web session
• a compatible Codex/browser bridge exposing globalThis.agent
• permission to use or open a visible ChatGPT tab

Ordinary shells should not have globalThis.agent. A browser_bridge_unavailable blocker from an ordinary shell is an expected safe result for browser-required calls.

File Upload Permissions

File attachment workflows need two separate permission gates:

1. Chrome extension gate: open chrome://extensions, choose the Codex/browser bridge extension, open Details, and enable Allow access to file URLs.
2. Codex app gate: in Codex settings, allow Google Chrome uploads under Computer Use > Google Chrome > Permissions > Uploads. Use the narrowest setting that fits the workflow; unattended smoke tests may need the always-allow setting.

If either gate is missing, stop with a permission blocker and tell the user which gate to check.

Host-Local Attachment Paths

Attachment paths must be absolute on the machine running the Node backend. Use the path form for that host operating system. On Linux/WSL backends, use paths such as /home/you/file.pdf or /mnt/c/work/file.pdf. On Windows backends, use fully qualified paths such as C:\Users\you\file.pdf. If a Windows-looking path is rejected on macOS/Linux, do not retry with the same string. Convert it to the backend host's real path, for example /home/you/file.pdf for a Linux/WSL backend.

Use chatgpt.files.preflight({ paths }) before long file workflows when local path validity is uncertain. It does not open ChatGPT or upload files; it validates host-local file metadata and returns structured blockers/warnings.

Source Setup

From a source checkout:

cd packages/node
npm ci
npm test
npm run build
npm run bundle
npm run bundle:backend

Then use the built bundle from a bridge-enabled host runtime:

import { createChatGPT } from "/absolute/path/to/codex-chatgpt-control/packages/node/dist/codex-chatgpt-control.bundle.mjs";

const chatgpt = createChatGPT({ agent: globalThis.agent });

Prefer normal package imports in projects that depend on the published npm package:

import { createChatGPT } from "codex-chatgpt-control";

Basic Runner Flow

const reviewer = chatgpt.agent({
  name: "reviewer",
  instructions: "Review carefully and return Markdown."
});

const result = await chatgpt.runner.run(reviewer, {
  input: "Review this design.",
  thread: { type: "new" },
  response: { format: "markdown" }
});

if (!result.ok) {
  console.log(JSON.stringify(result.interruptions ?? result, null, 2));
} else {
  console.log(result.output_text);
}

Instructions are visible prompt text by default. Use instructionsMode intentionally:

• visible_prefix: include instructions in the submitted user message.
• visible_setup_message: submit instructions as a separate visible setup turn.
• metadata_only: keep instructions local; they are not sent to ChatGPT.