Codex Chatgpt Bridge

Codex ChatGPT Bridge

Use this skill as the single entrypoint for coordinating Codex, ChatGPT, a scoped local MCP bridge, Chrome, and optional Cloudflare tunnels.

Core principle:

• Codex is the execution owner.
• ChatGPT is the reasoning and review partner.
• The local bridge is a scoped local access bridge.
• Chrome is the message transport.

Default posture:

• Codex owns source edits, tests, builds, git operations, local verification, and final reporting.
• ChatGPT owns high-depth reasoning, broad review, visual/PDF/screenshot analysis, and independent go/no-go critique.
• The local bridge defaults to one narrow workspace, read-only access, and no secrets.
• ChatGPT recommendations are advice until Codex verifies them locally.

Choose The Mode

Use bridge operations when the user asks to start, stop, inspect, repair, or configure ChatGPT access to a local project through the bridge.

Read references/bridge-operations.md for:

• local_bridge.ps1 start, stop, status, and doctor flows
• Cloudflare Quick Tunnel and Worker-proxy setup
• ChatGPT app/OAuth setup through Chrome
• on/off semantics that preserve ChatGPT configuration without leaving the workspace reachable
• service lifecycle and common failure handling

Use task routing when the user asks whether Codex, ChatGPT, subagents, or the local bridge should handle a task.

Read references/router-policy.md for:

• NORMAL and TOKEN_SAVING operating modes
• route classes
• permission levels
• ChatGPT Task Packet format
• ChatGPT Action Manifest format
• Codex ingestion rules
• token-saving policy
• security rules
• hardware/KiCad and debugging workflows

Use examples only when drafting a concrete handoff.

Read references/examples.md for:

• KiCad hardware review packets
• paper/code review packets
• complex bug packets
• image/PDF visual review packets
• ChatGPT Architect workflow (spec -> tasks -> per-task Codex execution prompt)

Read references/hook-design.md only when designing automation around this policy.

Read references/agents-snippet.md only when adding project-level AGENTS.md guidance.

Service Switch

Use the controller for normal lifecycle operations. It stores a non-secret profile separately from transient runtime state, serializes mutations with a mutex, treats Reboot as an alias of one verified Restart transaction, refreshes Worker KV in strict mode, and checks the local, Quick Tunnel, and stable Worker endpoints before reporting success.

$skill = "$env:USERPROFILE\.codex\skills\codex-chatgpt-bridge"
$controller = "$skill\scripts\bridge_controller.ps1"

powershell -ExecutionPolicy Bypass -File $controller -Action Configure -ProjectRoot <path> -Tunnel cloudflare-worker -PublicBaseUrl https://bridge.example.workers.dev -InstallCloudflared

Controller semantics:

• Configure saves the default project root, explicit file-tool roots, tunnel mode, port, and stable public URL without storing secrets. Use -AllowedRoots "<root1>;<root2>" for multiple roots; ProjectRoot must be inside one of them.
• On records intentional running state, starts the bridge, refreshes Worker KV when required, and verifies the 200/401 health contract.
• Off records intentional stopped state, closes the runtime, and preserves the profile and ChatGPT app authorization.
• Restart and Reboot are the same single transaction. They refuse to reopen a bridge intentionally turned off with Off; use On first.
• Stop/restart cleanup is scoped to the configured listener port. If an unrelated process owns that port, preserve it and fail with a conflict instead of killing it.
• Status reports controller, desired, and runtime state without exposing credentials. It still contains local paths, PIDs, log paths, and tunnel URLs; redact it before sharing.
• Doctor returns a non-zero exit code when the bridge is unhealthy and reports security warnings for drive-root or user-profile-wide allowed roots.
• Rotate is the panic button: it stops the bridge, deletes persisted OAuth tokens (~/.devspace/oauth-state.json), and mints a new Owner password, so anyone who is or was connected is locked out. Use it after any suspected unauthorized access; then use On and re-authorize ChatGPT. See the threat-model section in references/bridge-operations.md.
• Off intentionally preserves ChatGPT app configuration, local bridge config, and authorization material so the next On can reuse the same ChatGPT app without recreating or reauthorizing.
• This is a safety switch, not an OAuth revoke. ChatGPT keeps the app connection record, but with the local service and tunnel stopped it cannot reach the workspace.
• For no ChatGPT reconfiguration across restarts, prefer a stable Worker/custom proxy or stable external tunnel. Raw temporary tunnel URLs can change after restart.

For automated Worker KV refresh, store the minimum-scope Cloudflare token with Windows DPAPI. Never pass it on the command line:

powershell -ExecutionPolicy Bypass -File "$skill\scripts\set_cf_api_config.ps1" -Action Set -AccountId <account-id> -KvNamespaceId <namespace-id>

DPAPI protects the token at rest. A bridge and controller running as the same Windows user still share that user's authority, so DPAPI alone does not isolate an authorized run_shell.

The credential helper verifies a DPAPI round trip before writing, removes migrated plaintext cf-api.json, and controller-driven On / Reboot refuses legacy plaintext credentials. Automatic cloudflared installation must pass a valid Windows Authenticode signature check for Cloudflare, Inc. Shell-command logging defaults to disabled; enable DEVSPACE_LOG_SHELL_COMMANDS=true only when the user explicitly wants that local audit trail.

When the saved profile uses cloudflare-worker, the credential helper also creates or synchronizes local-only, non-credential worker-proxy.json metadata from the profile's stable URL and the supplied KV namespace. It still identifies deployment resources, so keep it out of git. Run Configure first, then the credential helper, then On.

Then operate and verify the bridge through the controller:

powershell -ExecutionPolicy Bypass -File $controller -Action On
powershell -ExecutionPolicy Bypass -File $controller -Action Reboot
powershell -ExecutionPolicy Bypass -File $controller -Action Off
powershell -ExecutionPolicy Bypass -File $controller -Action Status
powershell -ExecutionPolicy Bypass -File $controller -Action Doctor

# Panic button remains a direct, approval-gated runtime action.
powershell -ExecutionPolicy Bypass -File "$skill\scripts\local_bridge.ps1" -Action Rotate

Register the optional on-demand task only after user approval. It has no automatic trigger and calls the fixed Reboot action with MultipleInstances=IgnoreNew:

powershell -ExecutionPolicy Bypass -File "$skill\scripts\restart_task.ps1" -Action Install
powershell -ExecutionPolicy Bypass -File "$skill\scripts\restart_task.ps1" -Action Run

Run is asynchronous. Do not claim recovery until %LOCALAPPDATA%\devspace-bridge\controller-result.json reports success and controller Doctor passes.

Treat the scheduled task as reliability isolation only when it uses the same Windows account as DevSpace. For a real authorization boundary, run the bridge and controller under different OS identities with ACL-separated scripts, state, logs, and credentials.

Before starting a public tunnel, confirm:

• exact project root
• whether a public tunnel is acceptable
• whether the root is narrow enough for the task
• whether ChatGPT should get L1_READ_ONLY or L2_DIAGNOSTIC_COMMANDS

Never print owner tokens, OAuth secrets, browser cookies, or private keys into chat.

Operating Modes

Choose a routing mode before sending a task to ChatGPT.

NORMAL mode:

• Treat ChatGPT as a strong reasoning and review subagent.
• Codex performs enough local inspection to frame the task, then asks ChatGPT for independent reasoning, review, or alternatives when useful.
• Codex remains the owner of edits, tests, builds, git, and final verification.
• Use this when quality, collaboration, and confidence matter more than minimizing Codex token use.

TOKEN_SAVING mode:

• Treat Codex as the orchestrator and ChatGPT as the primary reader/reasoner for safe, non-mutating context work.
• Prefer ChatGPT plus the local bridge for broad file reading, long logs, large project orientation, architecture review, paper/hardware critique, and visual/PDF review.
• Codex should send compact task packets, avoid summarizing large context itself, then implement and verify only the accepted actions.
• Still keep secrets, writes, destructive actions, privileged commands, tests/build execution, git, and final claims under Codex or human approval.
• Route by marginal cost: hand a unit of work to ChatGPT only when the Codex tokens it would otherwise cost greatly exceed one slow bridge round-trip; keep many small mechanical ops in Codex, and batch ChatGPT into one dense turn instead of a tool-by-tool loop. See "Cost-Aware Routing" in references/router-policy.md.
• Use this when the user asks to save tokens or when context size is the main cost.

CHATGPT_ARCHITECT mode:

• The planning-inverted extreme of TOKEN_SAVING: ChatGPT is the architect/manager, Codex is the executor or integrator.
• ChatGPT owns the spec, UI/data design, task decomposition, per-task Codex prompt authoring, and review.
• Two execution profiles: in the default advice profile Codex writes every source change and verifies; in the independent-agent profile (L3_WORKSPACE_WRITE, opt-in by the user) ChatGPT writes source inside the one narrow root and self-verifies, then Codex reviews the diff, runs an independent check, and owns git plus the final claim.
• Either way keep the guardrails: a task is done only on an independent local check, not ChatGPT's say-so; ChatGPT never commits, pushes, installs, deletes beyond the task, touches secrets, or reaches outside the root; Codex feasibility-checks the plan first and does not over-decompose trivial work.
• Use this for long continuous builds, whole features/apps/games, or when avoiding Codex usage limits is the goal. See references/router-policy.md for the execution profiles, Architect Loop, and Codex Execution Prompt format.