# Codex MCP Bridge for ChatGPT

Use ChatGPT to work with Codex on your own computer. Register your projects, reuse your working procedures, continue existing work, and check progress from ChatGPT or the native macOS menu-bar app.

[Download releases](https://github.com/menaje/codex-mcp-bridge-for-chatgpt/releases) · [Setup guide](docs/setup.md) · [Skill library](docs/skills.md) · [Security model](docs/security.md)

This README describes the current **development branch**, with English screenshots refreshed on October 23, 2026. A downloaded release can have different features and screens; use the README at that release's Git tag, such as [v0.4.1](https://github.com/menaje/codex-mcp-bridge-for-chatgpt/tree/v0.4.1). A development build can retain the same product version while its features change. Screenshots use [sample data](docs/images/README.md).

## What you can do

- **Work on local projects from ChatGPT.** Ask Codex to inspect a registered folder, make an approved change, or continue an existing Agent. Activities group work around a goal; Agents keep execution context; Jobs record individual runs.
- **Reuse your procedures.** Keep review checklists, release instructions, and reference Markdown in the Bridge skill library. Import a folder or ZIP, edit the source, and restore earlier versions.
- **Choose your installation and account.** Use an existing Codex installation or a Bridge-managed CLI, and choose an existing login, a separate ChatGPT login, or a Bridge API-key connection.
- **Control model and execution settings.** Choose fixed or automatic model selection, edit model descriptions with version history, select processing speed, and set access and concurrency limits.
- **Keep track of work.** View work in progress, individual run history, and problem history, with available account usage above the lists. Save new conversations across restarts and choose app visibility separately.
- **Manage another Mac.** Pair a client Mac with a server on your private LAN or VPN and switch between saved servers.

ChatGPT → OpenAI Secure MCP Tunnel → Bridge on your server computer → Codex in a registered project folder.

## Choose a setup

| Your situation | Setup | What runs on this computer |
| --- | --- | --- |
| This Mac will run Codex | macOS app: **Run Server on This Mac** | App, helper, Bridge, Tunnel, and Codex |
| This Mac will manage another Mac | macOS app: [**Connect to Existing Server**](#manage-another-mac) | Client app only |
| Windows, Linux, or Mac managed from a terminal | Node.js server | Bridge, Tunnel, and Codex |

The native app requires macOS 13 or later. Server setups also need Node.js 22 or later, `tunnel-client`, an OpenAI Secure MCP Tunnel, and authenticated Codex. A client-only Mac needs the app and a pairing invitation. See [prerequisites and setup paths](docs/setup.md#what-you-need).

## Get started

### macOS app

1. Download the DMG matching your Mac from [Releases](https://github.com/menaje/codex-mcp-bridge-for-chatgpt/releases): `arm64` for Apple Silicon or `x64` for Intel. For the development screens shown here, [build the current app from source](#development).
2. Move **Codex MCP Bridge for ChatGPT** to Applications and open it.
3. Choose **Run Server on This Mac**. The assistant checks existing connection settings before asking for a Tunnel runtime key and Tunnel ID.
4. In **Codex Account & Installation**, explicitly select an existing installation or install a Bridge-managed CLI, then choose and verify an authentication connection.
5. Register your first existing project folder and confirm that the Bridge and Tunnel are ready.

<p align="center">
  <img src="docs/images/macos-connection-setup-light-en.png" alt="English macOS connection assistant showing the server and client roles" width="720">
</p>

The app is ad-hoc signed and not notarized. macOS may require approval in **System Settings → Privacy & Security** on first launch. Setup, installation ownership, and manual updates are covered in [Setup](docs/setup.md#macos-server-mode) and [Codex installations](docs/codex-runtimes.md).

### Windows, Linux, or a terminal-managed server

Install [Node.js 22 or later](https://nodejs.org/en/download), the [Codex CLI](https://learn.chatgpt.com/docs/cli), and [`tunnel-client`](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels#set-up-tunnel-client). Authenticate the CLI in the Codex home you intend this server to use. A new login in a shared home can affect other Codex clients; see [authentication connections](docs/codex-auth-connections.md).

Build the development branch using the [development commands](#development), then create the private runtime configuration outside your project folders using the [shell or PowerShell instructions](docs/setup.md#nodejs-server-on-windows-or-linux).

Set `CONTROL_PLANE_API_KEY` and `CONTROL_PLANE_TUNNEL_ID`, then run `npm run bridge:secure` and keep the process running. `npm run bridge:local` is for loopback development. Windows and Linux use the ChatGPT Settings and Dashboard cards for ordinary management.

### Connect to ChatGPT

1. Associate your Tunnel with the target ChatGPT workspace in [Platform tunnel settings](https://platform.openai.com/settings/organization/tunnels).
2. Enable **Developer mode** in ChatGPT **Settings → Security and login**. Workspace policy can control access.
3. Open [ChatGPT Plugins](https://chatgpt.com/plugins), create a developer connection, and choose **Connection → Tunnel**.
4. Select or enter the server's Tunnel ID and choose **No Auth** for the ordinary Bridge connection.
5. Add the connection in a new ChatGPT conversation and ask it to open Bridge settings. Register a project if you have not already done so.

Tunnel creation needs **Read + Manage** permission; running or selecting it needs **Read + Use**. Follow the [official Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) if the Tunnel is absent. Refresh the connection after an upgrade that changes tools, authentication, or card UI; close old cards and reopen the current ones. Routine restarts with the same build do not require Refresh.

## Try your first task

Use the exact name of a registered project. For a project named **Bridge Demo**, start with:

> Use Codex to inspect the registered project "Bridge Demo". Explain its structure and suggest one small improvement. Keep this task read-only.

Then continue the existing context:

> Continue the same Agent and investigate the improvement you suggested. Explain which files would change and how to verify it.

For an implementation, first allow the required access in Bridge settings and the server's access ceiling, then approve the specific change. Ask for the work's status or open the Codex Dashboard to see running work and run history.

Ordinary tasks and question answers automatically attach a blank goal relay, without a separate activation. It sends event references to the originating GPT, which reads exact original results and existing followup receipts before continuing approved work or requesting a decision. Dashboard opens only when requested. Host teardown stops that iframe; automatic GPT resumption while the app is closed is not guaranteed. See [relay delivery](docs/relay-delivery.md). Closing a screen or losing a connection does not cancel Codex. Return to the originating conversation and ask to read the existing work before starting anything again. See [task and result recovery](docs/chatgpt-setup.md#5-use-the-current-task-contract).

## Reuse procedures with the skill library

Bridge skills store your instructions as `SKILL.md` with optional reference Markdown files. ChatGPT searches and reads the selected version, then applies the procedure to your request. Reading a skill does not start Codex or change task permissions.

Open **Skill Library** (the book icon) in the macOS menu-bar popover. Create or import a skill, review the content and files, then save. Each save creates a version you can restore or export. See [the first-skill walkthrough](docs/skills.md#create-and-use-your-first-skill) for import and management details. Ask ChatGPT to find and use it:

> Find the Bridge skill "Code Review" and read it and its checklist. Use that procedure to review the registered project "Bridge Demo", then report the findings here.

<p align="center">
  <img src="docs/images/macos-skill-library-light-en.png" alt="English native Skill Library showing a reusable Code Review skill, its Markdown file tree, and rendered preview" width="820">
</p>

## Choose settings for your work

The native Settings sidebar separates General, Models & Execution, Projects, Codex Account & Installation, Connection, and Server. Shared changes save automatically in the native app; the ChatGPT card uses **Save settings**. Server limits use an explicit apply and restart. See [all settings](docs/setup.md#settings-reference).

| Setting | How it helps |
| --- | --- |
| Codex installation and [authentication](docs/codex-auth-connections.md) | Choose the executable separately from its account. Reuse an existing login, prepare a separate ChatGPT login, or explicitly select API billing. |
| Fixed or automatic model | Keep one model/effort pair, or let ChatGPT choose within your allowed catalog. In automatic mode, edit [model descriptions](docs/model-selection.md#user-model-descriptions) and restore earlier descriptions from history. |
| [Processing speed](docs/processing-speed.md#choose-a-speed) | Choose Standard or Fast for each new Job. Ultrafast requires verified access and is currently unavailable for new selection. Earlier settings keep their behavior until you explicitly choose a speed. |
| Conversation storage | Save new conversations across restarts or use memory-only context. App visibility is a separate choice; opening a conversation also needs accessible original storage and a released connection. |
| [Projects](docs/project-lifecycle.md) and [history](docs/work-history.md) | Archive to end active work safely; restore an archived registration or delete its Bridge records after cleanup. Choose 7, 30, 90 days, or unlimited retention for results and related history. |
| Language and concurrency | Apply an explicit language to the app and cards and limit concurrent Jobs. Automatic language follows the host showing each surface. |

<p align="center">
  <img src="docs/images/chatgpt-settings-light-en.png" alt="English ChatGPT Settings with processing speed, model policy, registered projects, conversation storage, and history retention" width="645">
</p>

<p align="center">
  <img src="docs/images/macos-codex-account-light-en.png" alt="English native Codex Account and Installation settings showing separate authentication and installation choices" width="820">
</p>

## Check work and usage

Open the menu-bar icon for server health, available weekly Codex usage, and **In progress / Execution history / Problem history** counts. Select one to expand its list, select it again to collapse it, and use **Show more** for further entries. Refresh explicitly to get a new snapshot.

<p align="center">
  <img src="docs/images/macos-menubar-usage-light-en.png" alt="English macOS menu-bar summary with weekly usage and current work counts" width="360" valign="top">
  <img src="docs/images/macos-dashboard-light-en.png" alt="English macOS In progress view showing grouped work, a running Agent, and an Agent waiting for input" width="360" valign="top">
</p>

The ChatGPT Dashboard switches between **This conversation** and **All conversations**. The three lists group work by Activity, Agent, and individual run. Problem history includes failed, interrupted, or cancelled runs and their recorded reasons. Each run shows its own model, reasoning level, speed selection, and time; a selected speed does not prove the actual processing tier.

<p align="center">
  <img src="docs/images/chatgpt-dashboard-light-en.png" alt="English ChatGPT Dashboard showing conversation scope, weekly usage, and the In progress, Run history, and Problem history tabs" width="645">
</p>

The Dashboard opens when requested. It manages and displays work without sending results into the chat or starting automatic followups. Read more about [questions](docs/gpt-questions.md), [history](docs/work-history.md), and [conversation handoff](docs/thread-lifecycle.md).

## Manage another Mac

On the server Mac, open **Settings → Connection**, enable **Manage This Server from Another Mac**, and create a pairing invitation. Paste it on the client Mac. It includes the server address and security identity, expires after five minutes, and can be used once.

<p align="center">
  <img src="docs/images/macos-pairing-invitation-light-en.png" alt="English macOS setting for creating a five-minute one-time pairing invitation" width="720">
</p>

Only one saved server is active at a time. Switching changes the source of status and shared settings. Project paths refer to folders on that server. Use a private LAN or VPN you control; see [remote client mode](docs/remote-client.md).

## Access and safety

- The Bridge begins with read-only access and binds to loopback by default.
- Register each permitted project folder explicitly. Keep runtime credentials outside those folders.
- Write or full access requires the server to allow it; settings cannot exceed that ceiling.
- The Bridge is for one trusted operator. Shared settings are not isolated by ChatGPT account.
- For stronger isolation, use a separate OS user, container, VM, or disposable project copy.

[MCP Events](docs/mcp-events.md) is a separate experiment disabled by default. Ordinary setup and approved followups use the normal conversation path. See [security boundaries](docs/security.md) before broadening access.

## Documentation

| Guide | Contents |
| --- | --- |
| [Setup and settings](docs/setup.md) | Prerequisites, platform setup, first task, and every user-facing setting |
| [Bridge skill library](docs/skills.md) | Create, import, use, version, restore, and export reusable procedures |
| [Codex installations](docs/codex-runtimes.md) and [authentication](docs/codex-auth-connections.md) | CLI ownership, manual updates, account choices, storage, and billing |
| [Model selection](docs/model-selection.md) and [processing speed](docs/processing-speed.md) | Allowed models, description history, speed scope, and execution evidence |
| [Native macOS app](docs/macos-app.md), [remote client](docs/remote-client.md), and [work history](docs/work-history.md) | Native settings, current work, retained runs, pairing, and recovery |
| [ChatGPT integration](docs/chatgpt-setup.md), [card tools](docs/card-tools.md), and [decision files](docs/standalone-decision-html.md) | Connection refresh, task contracts, questions, comparisons, and smoke checks |
| [Security](docs/security.md), [database](docs/database-schema.md), and [recovery](docs/state-upgrade-recovery.md) | Trust boundaries, retained data, backups, and upgrades |
| [MCP migration](docs/mcp-2026-07-28-migration.md), [input](docs/input-contracts.md), and [output](docs/output-contracts.md) | Current protocol and tool contracts |
| [UI releases](docs/ui-release-compatibility.md), [release process](docs/releasing.md), and [governance](docs/release-governance.md) | Card cache behavior, validation, and distribution gates |
| [Localization](docs/localization.md) and [text integrity](docs/text-integrity.md) | Translation source and Unicode policy |

## Development

```bash
git clone --branch dev https://github.com/menaje/codex-mcp-bridge-for-chatgpt.git
cd codex-mcp-bridge-for-chatgpt
npm ci
npm run check
```

On macOS, run `npm run macos:check` and `npm run macos:bundle`, then open `macos/build/Codex MCP Bridge for ChatGPT.app`.

Release identity and supported targets are defined in `release-manifest.json`. Historical attribution is in [UPSTREAM.md](UPSTREAM.md).

## License

MIT