codex-with-chatgpt

# Codex with ChatGPT ChatGPT thinks. Codex works. You (Codex) own execution: editing, shell, git, tests, recovery. ChatGPT owns high-level reasoning: understanding, planning, review, debug strategy. The C2C Bridge gives ChatGPT read-only MCP access to the current workspace, so control messages between you and ChatGPT stay tiny (< 1 KB) — ChatGPT pulls whatever data it needs by itself. **Golden rules** 1. NEVER paste file contents, diffs, or logs into ChatGPT. ChatGPT reads them through MCP. 2. NEVER show the user technical internals (MCP, OAuth, PKCE, tunnel, ports, localhost). Speak in terms of "连接 ChatGPT / 安全连接 / 配对". The only exception is the **guided manual ChatGPT setup** below: expose only the exact settings field labels/values the user must enter, without explaining internals. 3. The pairing code is the ONLY credential you may ever type into a browser. Never touch OAuth tokens, cookies, or session storage. 4. If something fails, run `c2c doctor` and repair silently. Only involve the user for logins, CAPTCHA, 2FA, explicit consent screens, or **guided manual ChatGPT setup** below — and then give them ONE action. Before the first ChatGPT connection on this machine, `c2c prefs --json`: - `setupMode` missing: tell the user exactly `setupChoicePrompt`, wait for 「1」or「2」, then `c2c prefs set --setup-mode auto|manual --json`. Do not start ChatGPT configuration until they answer. Do not guess. - `setupMode` is `manual`: skip automatic ChatGPT settings. Use guided manual from the start (chosen, not a failure). - `setupMode` is `auto`: automatic browser setup. Two explicit failures of the same configuration step after repair then enter guided manual. A browser/js timeout, a page still loading/generating, or waiting for user login/2FA does NOT count as a failure. Do not change the saved `setupMode` when falling back. `developerModeEnabled: true` means skip `#settings/Security` until a connector create fails because developer mode is required. Then open that page, enable it, and `c2c prefs set --developer-mode --json`. These prefs are for this machine, not per workspace. Do not ask again on reconnect or a second repo. A new computer (empty prefs) asks/checks once. 5. ALWAYS use the built-in in-app browser (iab) for every ChatGPT step. Follow **In-app browser (ChatGPT)** below. NEVER Computer Use (no screenshot-click). NEVER launch or control a third-party/external browser (Chrome, Safari, Edge…), and never use `open <url>` to hand off to one. - The ONLY exception: the user explicitly says the Cloudflare login must use their own browser session — that single Cloudflare login step may go through their browser; everything else stays in the built-in browser. - If the user asks to run ChatGPT in their own browser, refuse politely and explain: "Codex 需要持续调用 ChatGPT 和配置连接，这会频繁操作页面，可能影响 你浏览器的正常使用。ChatGPT 只能跑在内置浏览器里。" Only if the user replies with an explicit "我愿意承担影响" may you proceed in their browser; otherwise keep ChatGPT in the built-in browser, every time they ask. 6. Conversation reuse depends on `c2c session --json` → `conversation.mode` (see Conversation management). Do not invent a second mode. - **long-chat** (legacy session file, or the user opted out): ONE ChatGPT conversation per workspace. Never silently start a new chat. - **project** (new workspaces, or an existing workspace that opted in): ONE ChatGPT Project (collection) per workspace. Same Codex conversation reuses the ChatGPT chat URL saved in THIS thread. A new Codex conversation opens a new chat from the Project collection page — never `goto` `https://chatgpt.com/` to create it, and never reuse another Codex conversation's chat URL just because `session.url` exists. Each workspace also has exactly ONE ChatGPT connector. Do not create a second connector for the same workspace. Other workspaces may have their own connectors — never edit those. 7. After first-time setup, never ask the user to approve writing C2C's local settings directory. Run `c2c sandbox-allow --json` (idempotent). If it fails with EPERM / Operation not permitted, request elevated permissions and retry ONCE. After `{ "alreadyAllowed": true }` or `{ "added": true }`, stay silent. 8. ChatGPT pages: only the URLs in **In-app browser (ChatGPT)**. Never start from chatgpt.com and click through menus. 9. **Doctor gate.** After `c2c doctor --json`, do not `goto` ChatGPT and do not send `[C2C]` until local is green — except the reconnect settings pages when `chatgptRepair.needed` is true. Not green: - `report.bridge.ok` is not true - `report.mcp.ok` is not true (unauthenticated local `/mcp` must be 401) - sandbox / state-dir write failed (EPERM) - this workspace used to have a public URL and the tunnel is down - `chatgptRepair.needed` is true (fix the connector first, then doctor again) - `namedRepair.needed` is true (user must log in to Cloudflare, then doctor again. Do not Delete the ChatGPT connector — the address did not change) - `report.bridge` says 状态无法确认: the local bridge may still be running. Do not `c2c start`, do not Delete the connector, do not treat it as `chatgptRepair`. Wait and run doctor again. If doctor is already green and `chatgptRepair.needed` is false, do not `c2c restart`, do not start a second tunnel, and do not Delete the connector. ChatGPT/IAB-only errors are not permission to churn the public address. A ChatGPT-side 401 after a sent message is different: repair then, do not treat it as permission to skip this gate next time. ## In-app browser (ChatGPT) Official skill: `control-in-app-browser`. These C2C rules override defaults that close the tab, hide the window, or stall on the settings page. 1. **Surface.** Once per Codex session: `setupBrowserRuntime()`, then `const iab = await agent.browsers.get("iab")`. Reuse `iab`. Do not re-read `documentation()` if it is already bound. Never `getDefault()`, `getForUrl()`, or Computer Use. 2. **One tab.** Create the ChatGPT tab once (`tabs.new()`). After that, only `tab.goto(...)` to switch URLs. If the tab still exists, claim it — never open a second ChatGPT tab. Do not `goto` the URL you are already on. 3. **Foreground + keep (standby).** Right after opening or claiming the tab: - `await (await iab.capabilities.get("visibility")).set(true)` — first-time setup and ChatGPT chatting stay in front of the user so they can watch. - `await tab.markHandoff()` immediately, then again at the start and end of every turn. After setup succeeds or the C2C chat is open, also `await tab.markDeliverable()`. Never close this tab. Finished, waiting for the user, or timed out: leave it marked (standby). Do not let default turn cleanup close it. 4. **URLs only** (same tab, `goto` — never hunt menus): - 开发人员模式: `https://chatgpt.com/#settings/Security` (skip when `c2c prefs --json` has `developerModeEnabled: true`) - 插件总管: `https://chatgpt.com/plugins` - 加插件: `https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins` - 新对话 (long-chat only, and only if no saved chat): `https://chatgpt.com/` - Saved C2C chat: `conversation.chatUrl` / `session.url` (long-chat, or the chat already bound in THIS Codex conversation) - Saved Project collection: `conversation.projectUrl` (`https://chatgpt.com/g/g-p-…/project`) Never click Reconnect / Refresh on an existing connector. The old address is dead and that page hangs on "This site cannot be reached". When the address changed: Delete THIS workspace's `connectorName` only, then create it again via the 加插件 URL (same name, new Server URL). Do not put that public address into Project instructions — write the connector **name** only. 5. **Do not wait for 8 tools** on the settings page. "Connected" / authorize success / pairing accepted is enough. Confirm tools in the conversation with `workspace_info`. 6. **Batch.** Fill a known form in one Playwright / `js` script when you can. After an action, one cheap DOM check. Do not screenshot-poll. 7. **One conversation, Chat mode.** The first ChatGPT chat is the C2C conversation. Chat and Work (聊天 / 工作) are separate: a Work conversation cannot become Chat. On every NEW conversation, if a Chat/Work switcher is visible (often top-left), confirm **Chat** is selected before the boot prompt. If it is Work, do not continue there — Switch to a new Chat conversation (HANDOFF). If no switcher is visible, do not hunt menus; continue. Send the boot prompt and the workspace_info check in that Chat conversation. Confirm the reply names the current workspace **before** saving or replacing the session URL. If validation fails, keep the old saved URL. Do not open a throwaway verify chat and later another C2C chat. A collection or chat page that shows only `Retry` / `重试` is a navigation error, not generation and not a pairing failure. Reuse the same iab tab. Try Retry once. If it stays Retry-only, `goto` the last working chat URL from this thread (or `session.url` if that is the only saved chat), then click the on-page `Open … project` / `打开“… ”项目` link — that same-site hop is allowed. Do not treat the URLs-only rule as forbidding this link. On the collection, require the project chat list and new-chat composer before continuing. Keep the old saved URL/checkpoint until the replacement chat passes workspace_info. Do not `session clear`. Do not use Computer Use. 8. **Wait for a ChatGPT reply (do not hold one long browser wait).** After you send INIT, EXECUTED, boot, or the workspace_info check: `markHandoff`, keep the tab foreground, and stay in this same task. Do not `waitFor` 5 minutes and do not screenshot-poll. Every 20–30 seconds, one cheap DOM check: - still generating → wait again (do not type, do not resend); - `STATE: PLAN` / `DONE` / `BLOCKED` / the verify workspace name → read it and continue the existing protocol; - visible error → repair; do not start a new chat. A browser/js timeout is not failure. Claim the same tab, read the page, keep standby. If ChatGPT is still thinking, keep polling. Never open a second tab and never resend INIT/EXECUTED just because a wait timed out. ## Locations - The codex-with-chatgpt checkout lives at: `<ACTUAL_CHECKOUT_PATH>` (installer/update MUST replace this line in the installed Skill with the user's actual checkout path.) - Codex home: let `<codex-home>` be a non-empty `CODEX_HOME` when set; otherwise use `~/.codex` (`%USERPROFILE%\.codex` on Windows). - CLI: let `<checkout>` mean the path on the previous line; run `node "<checkout>/bin/c2c.js" <command>` (or `c2c <command>` if globally linked). All commands support `--json` for parsing. - If the checkout has no `node_modules` or no `dist/`, first run `corepack pnpm install && corepack pnpm build` inside it. - For commands that act on the user's project (`setup`, `doctor`, `session`, `restart`, `start`, `stop`, `status`, `pair`, `unpair`, `logs`, `workspace`, `record`, `tunnel status`, `tunnel choose`), pass `-w <workspace root>` (the project the user is working on, NOT the c2c repo). - Do not add `-w` to machine-wide commands: `update-check`, `sandbox-allow`, `prefs`, `tunnel login`. They still accept and ignore `-w`, so a leftover flag must not fail the command. ## Daily update check At the START of every workflow below (before anything else), run these two commands (both are cheap / cached; never mention them unless an update exists): 1. `c2c update-check --json` (do not pass `-w`) 2. `c2c sandbox-allow --json` (do not pass `-w`) — writes the C2C state directory into Codex's sandbox `writable_roots` (macOS: `~/Library/Application Support/codex-with-chatgpt`; Windows: `%LOCALAPPDATA%\codex-with-chatgpt`; config file is `<codex-home>/config.toml`; see **Locations**). If already allowlisted, this is a no-op and does not trigger elevation. - `{ "updateAvailable": false }` → continue silently. Never mention the check. - `{ "updateAvailable": true }` → tell the user one line: "检测到 Codex with ChatGPT 有新版本，我先更新一下（约 1 分钟），随后继续你的任务。" Then run the update workflow below, and CONTINUE the original task afterwards. ## Workflow: update（"更新 Codex with ChatGPT"，or triggered by the daily check） Inside the checkout directory (see Locations): 1. `git pull --ff-only` (if it fails due to local edits: `git stash && git pull --ff-only`). 2. `corepack pnpm install && corepack pnpm build`. 3. Re-install the Skill: copy `skill/SKILL.md` to `<codex-home>/skills/codex-with-chatgpt/SKILL.md`, then fix the "checkout lives at:" line in the copy to the actual checkout path. 4. `c2c sandbox-allow --json` (so existing installs pick up the sandbox allowlist), then `c2c restart -w <workspace>` so the bridge runs the new code, then `c2c update-check --force --json` to refresh the cache (should now report up to date). 5. Tell the user "✓ 已更新到最新版本" — then resume whatever task triggered this. (The updated SKILL.md takes effect from the next Codex session; that's expected.) ## Connection choice (once per workspace) Ask this **before** the public address exists (`c2c setup` / first `doctor --fix` that starts a tunnel). Do not mention tunnels, wrangler, DNS, or hostnames. Speak only of 临时地址 / 固定域名 / 登录 Cloudflare. 1. `c2c tunnel status -w <workspace> --json` 2. If `needsChoice` is false: do not ask again. 3. If `needsChoice` is true: tell the user exactly `userPrompt` and wait. - 没有账号 / 没有域名 / 临时 / 不用 → `c2c tunnel choose -w <ws> --mode quick --json` - 有域名（例如 example.com）→ first tell them `loginPrompt`, then `c2c tunnel choose -w <ws> --mode named --zone <domain> --json`. This may open the user's own browser (the Cloudflare exception in Golden rule 5). Wait until the command finishes. If they said they have an account but gave no domain: ask once for the domain. If the command returns `need: "zone"`, ask once and retry. If `fallback` is true: tell them `userMessage` and continue on the temporary address. Do not retry named unless they ask. 4. Never put connection credentials in the project. The CLI stores them in the C2C state directory. ## Workflow: first-time setup（"使用 Codex with ChatGPT 完成首次配置"） 1. Detect prerequisites yourself: `node --version` (>= 20), and check `cloudflared`. - If cloudflared is missing on macOS run `brew install cloudflared`; on Windows use `winget install Cloudflare.cloudflared`. Do this yourself; don't ask. 2. If the c2c repo has no `node_modules`, run `pnpm install && pnpm build` in it. 3. Run `c2c sandbox-allow --json`, then **Connection choice**, then `c2c setup -w <workspace> --json`. `sandbox-allow` edits Codex `config.toml` only — it adds C2C's state directory to `[sandbox_workspace_write].writable_roots` so later chats can write logs without elevation. If the write is denied, request approval and retry once. → returns `{ mcpUrl, pairingCode, workspaceName, connectorName, ... }`. `connectorName` is this workspace's plugin title (legacy installs stay `Codex with ChatGPT`; additional workspaces get `Codex with ChatGPT · <name>`). Pairing codes expire in ~5 minutes. Do not mint one until the ChatGPT Authorize / pairing form is on screen: run `c2c pair --json` then type that code immediately. Doctor does not pre-mint a code. 4. `c2c prefs --json` (this machine, not this workspace). - If `setupMode` is null: tell the user exactly `setupChoicePrompt`. Wait for「1」or「2」. Then `c2c prefs set --setup-mode auto` or `--setup-mode manual`. Do not open ChatGPT settings and do not start automatic configuration until they answer. Do not default to auto. - If they later ask to switch: same `c2c prefs set --setup-mode` command. Do not re-ask on a later workspace or on reconnect. - `setupMode: "manual"`: skip step 5's automatic ChatGPT settings. Go to **Guided manual ChatGPT setup** (chosen). Opening line: `接下来用手动教学配置。一次只需要做一个操作。` Do not say 自动配置没有成功. - `setupMode: "auto"`: continue with step 5. Keep the two-failure fallback. 5. Open ChatGPT on the ONE iab tab (see **In-app browser**). Foreground + markHandoff immediately. Same tab, `goto` only: - 开发人员模式: skip `https://chatgpt.com/#settings/Security` when `developerModeEnabled` is true. Otherwise open it, enable 开发人员模式 ("Developer mode") if it is off, then `c2c prefs set --developer-mode`. Never record it as off. If creating the connector later says developer mode is required, open this page, enable it, save `--developer-mode`, and retry create — do not skip that recovery. - 已有该 `connectorName`: `https://chatgpt.com/plugins` — Delete it (never Reconnect). Then `goto` the 加插件 URL below. - 还没有 / 刚删掉: `https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins` Operate ONLY on `connectorName` from step 3: - If that exact name exists: Delete it, then create it again. Never Reconnect, never edit-in-place, never open the old Server URL. - If it does not exist: create one with that exact name. - Never rename, delete, or edit a connector that belongs to another workspace. - Description: `Securely connect ChatGPT to the current Codex workspace for planning and review.` - Server URL: the `mcpUrl` from step 3 - Authentication: OAuth Fill the known form in one script when you can. Then Connect / Authorize. Only then run `c2c pair --json` and type that code. As soon as it shows Connected / authorized / pairing accepted, continue — do NOT wait for 8 tools on this page. 6. Same tab: open the first C2C chat per **Conversation management** (Project collection for a new workspace; `https://chatgpt.com/` only in long-chat). Confirm Chat mode per **In-app browser** §7 (if it is Work, open a new Chat conversation instead). Send the boot prompt from `docs/protocol.md` §Boot Prompt, then (same chat) send: `Use the "<connectorName>" connector: call workspace_info and read hello-style top-level file. Reply with the workspace name.` Confirm the reply matches `workspaceName` (wait per **In-app browser** §8). Only then save the chat URL with `c2c session set` (see Conversation management). If the name does not match, do not save. markDeliverable. 7. Report to the user exactly in this shape (no internals): ``` Codex with ChatGPT ✓ 当前项目已识别 ✓ Workspace Bridge 已启动 ✓ 安全连接已建立 ✓ ChatGPT 已连接 ✓ 文件读取测试通过 Ready. ``` If a login wall appears (ChatGPT, Cloudflare): stop, tell the user the ONE thing to do ("请登录 ChatGPT，完成后告诉我'好了'"), then continue. ### Guided manual ChatGPT setup Enter this path when `setupMode` is `manual` (chosen at the start), or when automatic ChatGPT browser configuration fails twice at the same explicit setup/reconnect step after `c2c doctor` / repair. Do NOT enter the failure path for a browser/js timeout without a visible error, a page that is