# zhenyu98/codex-chatgpt-bridge architecture

> Architecture diagram of the GitHub repository zhenyu98/codex-chatgpt-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhenyu98/codex-chatgpt-bridge
- Repository: https://github.com/zhenyu98/codex-chatgpt-bridge

## Overview

Codex ChatGPT Bridge is an agent skill plus external PowerShell controls, not an MCP server: it uses upstream DevSpace for MCP, OAuth, and project tools. The principal workflow routes planning and review to ChatGPT, then has Codex execute and verify locally. Separate lifecycle scripts manage the bridge, recovery, and stable public-link configuration. Relationships and capabilities below come from the README; source excerpts were not provided, so implementation-level calls are not inferred.

Main entry points: [`skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1`](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1) (Bridge controller), [`skills/codex-chatgpt-bridge/SKILL.md`](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/SKILL.md) (Routing skill), [`skills/codex-chatgpt-bridge/scripts/restart_task.ps1`](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/restart_task.ps1) (Scheduled recovery), [`skills/codex-chatgpt-bridge/scripts/set_cf_api_config.ps1`](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/set_cf_api_config.ps1) (Worker link config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Agent workflow"]
  node_skill["Routing skill<br/>[SKILL.md]"]
end

subgraph group_controls["Lifecycle controls"]
  node_controller["Bridge controller"]
  node_local_bridge["Local bridge controls<br/>[local_bridge.ps1]"]
  node_runtime_state[("Desired/runtime state")]
  node_recovery_task["Scheduled recovery<br/>[restart_task.ps1]"]
end

subgraph group_connectivity["Bridge connectivity"]
  node_devspace["DevSpace MCP"]
  node_link_config["Worker link config"]
  node_tunnel["Tunnel / Worker"]
end

node_coding_agent(("Coding agent"))
node_chatgpt(("ChatGPT"))
node_codex(("Codex execution"))

node_coding_agent -->|"uses guidance"| node_skill
node_skill -->|"routes planning"| node_chatgpt
node_chatgpt -->|"reviews project"| node_devspace
node_devspace -->|"provides tools"| node_chatgpt
node_codex -->|"executes locally"| node_devspace
node_codex -->|"verifies work"| node_coding_agent
node_coding_agent -->|"invokes lifecycle"| node_controller
node_controller -->|"records desired state"| node_runtime_state
node_controller -->|"controls lifecycle"| node_devspace
node_controller -->|"controls tunnel"| node_tunnel
node_recovery_task -->|"runs reboot"| node_controller
node_link_config -->|"refreshes upstream"| node_tunnel

click node_skill "https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/SKILL.md"
click node_controller "https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1"
click node_local_bridge "https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/local_bridge.ps1"
click node_runtime_state "https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1"
click node_recovery_task "https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/restart_task.ps1"
click node_link_config "https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/set_cf_api_config.ps1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill toneBlue
class node_controller,node_local_bridge,node_runtime_state,node_recovery_task toneAmber
class node_devspace,node_link_config,node_tunnel toneMint
class node_coding_agent,node_chatgpt,node_codex toneIndigo
```

## Components

### Agent workflow

- [Routing skill](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/SKILL.md): `skills/codex-chatgpt-bridge/SKILL.md`

### Lifecycle controls

- [Bridge controller](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1): `skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1`
- [Local bridge controls](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/local_bridge.ps1): `skills/codex-chatgpt-bridge/scripts/local_bridge.ps1`
- [Desired/runtime state](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1): `skills/codex-chatgpt-bridge/scripts/bridge_controller.ps1`
- [Scheduled recovery](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/restart_task.ps1): `skills/codex-chatgpt-bridge/scripts/restart_task.ps1`

### Bridge connectivity

- **DevSpace MCP**
- [Worker link config](https://github.com/zhenyu98/codex-chatgpt-bridge/blob/main/skills/codex-chatgpt-bridge/scripts/set_cf_api_config.ps1): `skills/codex-chatgpt-bridge/scripts/set_cf_api_config.ps1`
- **Tunnel / Worker**

### Other components

- **Coding agent**
- **ChatGPT**
- **Codex execution**

## Connections

- Coding agent → Routing skill: uses guidance (evidence: `README.md`)
- Routing skill → ChatGPT: routes planning (evidence: `README.md`)
- ChatGPT → DevSpace MCP: reviews project (evidence: `README.md`)
- DevSpace MCP → ChatGPT: provides tools (evidence: `README.md`)
- Codex execution → DevSpace MCP: executes locally (evidence: `README.md`)
- Codex execution → Coding agent: verifies work (evidence: `README.md`)
- Coding agent → Bridge controller: invokes lifecycle (evidence: `README.md`)
- Bridge controller → Desired/runtime state: records desired state (evidence: `README.md`)
- Bridge controller → DevSpace MCP: controls lifecycle (evidence: `README.md`)
- Bridge controller → Tunnel / Worker: controls tunnel (evidence: `README.md`)
- Scheduled recovery → Bridge controller: runs reboot (evidence: `README.md`)
- Worker link config → Tunnel / Worker: refreshes upstream (evidence: `README.md`)
