Codex ChatGPT Bridge

English | 中文

A dual-plane bridge for using ChatGPT Web as a planning, review, and research brain while Codex keeps execution and final judgment.

The project combines two pinned MIT foundations:

• chicogong/codex-chatgpt-web-orchestrator for routing, receipts, lifecycle, recovery, and governance.

• codex-with-chatgpt for the C2C control protocol, read-only workspace MCP, OAuth 2.1, pairing, Cloudflare tunnels, execution records, and session recovery.

The Codex In-app Browser is the preferred control surface. A headed system browser is fallback-only and requires explicit user approval.

Permanent policy

ChatGPT Work is forbidden.

The route parser, adapter manifest validation, state machine, tests, MCP policy, and verifier all reject Work. The supported modes are:

• chat-pro: architecture analysis, code review, critique, synthesis, and reverse-challenge.

• deep-research: source-heavy research with citations and long-running recovery.

Related MCP server: C2C Bridge

What is implemented

• Receipt-backed authorization and prompt fingerprinting.

• submission.count <= 1 with explicit committing and committed states.

• Conversation identity recovery without blind resend.

• generating, complete, partial, incomplete, blocked, and unknown outcomes.

• Separate raw response, compressed working view, and verification record.

• Code-review file and line structural checks.

• Deep Research HTTPS citation checks and semantic-verification handoff.

• Read-only workspace MCP with code, search, git, test, and sanitized execution tools.

• INIT -> PLAN -> EXECUTING -> EXECUTED -> REVIEW -> DONE/BLOCKED governance.

• Sanitized execution records and HANDOFF support.

• Read-only external data-source contracts with row, byte, and timeout limits.

• Offline tests that never open a browser or use a ChatGPT account.

Repository layout

.codex-plugin/       Codex plugin manifest
adapters/            Capability manifests
docs/                Deployment, live smoke, and vendor patches
examples/            Example manifests and observations
references/          Bridge, data-plane, lifecycle, and output contracts
schemas/             Receipt, verification, and read-only data-source schemas
skills/              Codex skills
src/ccw/             Local Python governance and integration package
tests/               Offline unit and CLI tests
vendor/              Pinned governance and C2C bridge sources
scripts/             Windows launchers, tests, and dependency helpers

Quick start

Run the local governance tests:

.\scripts\test.ps1

Run the vendored C2C bridge tests:

.\scripts\test-c2c.ps1

Validate the plugin:

.\scripts\validate-plugin.ps1

Check the C2C environment and build the bridge:

.\ccw.cmd c2c detect
.\ccw.cmd c2c build

Expose it to ChatGPT with the relay: docs/deployment.md.

Integrated C2C loop

The control plane sends tiny [C2C] state messages through the In-app Browser. The data plane exposes read-only workspace MCP tools so ChatGPT can inspect code, diffs, search results, git state, tests, and sanitized execution records itself.

.\ccw.cmd c2c exec -- start --tunnel
.\ccw.cmd c2c exec -- doctor

Governance transitions are mirrored locally:

.\ccw.cmd cycle set <run_id> --state INIT --iteration 0 --task-id <task_id>
.\ccw.cmd cycle set <run_id> --state PLAN --iteration 1
.\ccw.cmd cycle set <run_id> --state EXECUTING --iteration 1
.\ccw.cmd cycle record-execution <run_id> `
  --iteration 1 `
  --changed-file src/a.ts `
  --tests "27 passed" `
  --exit-status ok `
  --command "pnpm test" `
  --output-file .\test.log
.\ccw.cmd cycle set <run_id> --state EXECUTED --iteration 1

Control messages stay under 1 KB and never contain file bodies, diffs, or logs. Detailed output is stored locally, sanitized, and exposed to ChatGPT only through the read-only data plane.

Pro review lifecycle

# 1. Create a run with the exact prompt.
.\ccw.cmd run init `
  --mode chat-pro `
  --task-kind review `
  --workspace E:\path\to\repo `
  --adapter-manifest .\adapters\native-codex-browser.example.json `
  --prompt-file .\prompt.md

# 2. Authorize the exact prompt.
.\ccw.cmd run authorize <run_id>

# 3. Record read-only In-app Browser preflight evidence.
.\ccw.cmd run preflight <run_id> --observation .\observation.json

# 4. Record the single submission intent and acknowledgement.
.\ccw.cmd run begin-submit <run_id>
.\ccw.cmd run confirm-submit <run_id> --conversation-identity <private-id>

# 5. Capture, compress, verify, and finalize.
.\ccw.cmd run capture <run_id> --raw-file .\response.md --terminal-signal
.\ccw.cmd run compress <run_id>
.\ccw.cmd run verify <run_id>
.\ccw.cmd run finalize <run_id>

Raw ChatGPT output is authoritative. compressed.json is only a bounded working view. Codex must verify every finding and decision-critical claim locally.

Deep Research lifecycle

Use --mode deep-research --task-kind source-research or research-report.

The same receipt and single-submission rules apply. Deep Research can run for a long time, but timeout never authorizes a second submission. Capture the complete report and ordinary HTTPS citations before compression.

Recovery

.\ccw.cmd run recover <run_id> --observation .\recovery.json

Recovery always prefers the same conversation identity. If identity is lost and no saved capture exists, the run becomes unknown; it is never silently rerun.

Read-only data plane

Workspace MCP is the primary data plane. Optional production data sources must satisfy references/data-plane.md:

• Read-only views or replicas.

• OAuth 2.1 for remote endpoints.

• Hard row, byte, and timeout limits.

• Sensitive-field redaction and audit logs.

• No write, shell, commit, deployment, or administrative tools.

Validate an external data-source contract:

.\ccw.cmd data validate --manifest .\examples\readonly-data-source.sqlite.json

Adapter contract

Required capabilities:

• send

• observe

• capture

• stable_identity

Route capability:

• chat_pro

• deep_research

Adapters must not expose Work. See references/bridge-contract.md.

Deployment

The bridge listens on loopback only. Expose it with the relay (one stable public URL, no inbound ports): docs/deployment.md.

# on a machine that runs a bridge (after the relay exists)
powershell -ExecutionPolicy Bypass -File deploy\install.ps1 -WorkspacePath <workspace root>

• deploy/relay-setup.sh prepares a relay host (Tailscale Funnel).

• deploy/install.ps1 runs the client + Codex plugin setup in one command.

• deploy/install-client.ps1 prepares a machine that runs a bridge.

• scripts/startup.ps1 is the logon supervisor: it keeps the bridge and the reverse tunnel alive, so a reboot needs no manual step.

One workspace can cover many repositories (point the bridge root at their parent directory): workspace_info lists them and git_status/git_diff take a repo argument. See docs/deployment.md.

Always use the In-app Browser for ChatGPT pages. Do not launch a headed system browser.

Live smoke

Real browser/account smoke is separate from offline tests. Follow docs/live-smoke.md only with explicit authorization to use the signed-in ChatGPT account.

Private data

Runtime state is stored in CCW_HOME, default ~/.ccw/runs/<run_id>. private.json and receipt.private.json contain raw conversation identities and must never be committed or shared. Public receipts contain commitments only.

Upstream

See UPSTREAM.md and THIRD_PARTY.md.