ChatGPT Codex Bridge

简体中文 | Security | Contributing

A local-first MCP bridge that lets ChatGPT inspect registered Codex projects, read Codex session history, and dispatch confirmed tasks to the local Codex CLI.

What it does

• Discovers projects already registered in Codex Desktop, without granting access to the entire home directory.

• Runs analysis and planning in the Codex read-only sandbox.

• Requires a short-lived, single-use confirmation token before workspace writes.

• Lists and reads visible Codex sessions with cursor pagination and redaction.

• Builds bounded project-history context without loading multi-gigabyte histories into memory.

• Creates and continues persistent Codex Desktop sessions through the local Codex app-server protocol.

• Hands ChatGPT-provided context to Codex as untrusted reference text, with secret detection.

• Uses background jobs so long Codex tasks do not hold an MCP tunnel request open.

The bridge does not expose an arbitrary shell tool and does not listen on a public port. Remote access is provided by the official OpenAI Secure MCP Tunnel client.

Architecture

flowchart LR
    A[ChatGPT] -->|MCP connector| B[OpenAI Secure MCP Tunnel]
    B -->|outbound tunnel| C[tunnel-client on your machine]
    C -->|stdio MCP| D[ChatGPT Codex Bridge]
    D -->|sandboxed commands| E[Codex CLI]
    D -->|read-only indexes| F[Codex projects and sessions]
    D -. optional local IPC .-> G[Codex Desktop sidebar refresh]

The optional sidebar refresh path depends on a private, unsupported Codex Desktop extension and is not included in this repository. The core bridge works without it; newly created persistent sessions may require a Codex Desktop restart before they appear in the sidebar.

Requirements

• macOS or Linux with Python 3.11+

• A working codex CLI installation and sign-in

• Codex Desktop for automatic project discovery and session history features

• Homebrew for the documented Tunnel installation path

• OpenAI organization access to Secure MCP Tunnels

This project is currently tested on macOS. Windows is not supported because the optional Desktop notification path uses Unix sockets.

Quick start

git clone https://github.com/AaAndrew233/chatgpt-codex-bridge.git
cd chatgpt-codex-bridge
./scripts/bootstrap.sh

bootstrap.sh creates a local virtual environment, installs the reviewed dependency lock, and generates untracked config.json and .mcp.json files. It never overwrites existing configuration.

Open config.json and choose one authorization source:

{
  "codex_command": "codex",
  "model": null,
  "codex_project_catalog": "~/.codex/.codex-global-state.json",
  "allowed_roots": []
}

• Keep model as null to inherit your current Codex configuration.

• Keep allowed_roots empty to use only projects registered in Codex Desktop.

• Add narrow project directories to allowed_roots only when automatic discovery is unavailable.

• Never authorize / or your home directory. The bridge rejects both.

Run the local checks:

./scripts/check_public_release.py
.venv/bin/python -m unittest discover -s tests -v

Connect through Secure MCP Tunnel

Install the official client:

brew install openai/tools/tunnel-client
tunnel-client --version
tunnel-client help quickstart

Store the runtime key in a file outside this repository and restrict its permissions:

chmod 600 /ABSOLUTE/PATH/TO/runtime-key

Create a managed background runtime. Replace all placeholder values:

tunnel-client runtimes connect \
  --alias codex-bridge \
  --profile codex-bridge \
  --tunnel-id '<YOUR_TUNNEL_ID>' \
  --runtime-api-key 'file:/ABSOLUTE/PATH/TO/runtime-key' \
  --mcp-command '/ABSOLUTE/PATH/TO/chatgpt-codex-bridge/scripts/run_server.sh'

Verify that the managed runtime is running, healthy, and ready:

tunnel-client runtimes status codex-bridge --json

Then create or refresh the connector in ChatGPT connector settings. The official Tunnel onboarding guide is the source of truth for organization roles, tunnel IDs, runtime keys, and current commands: openai/tunnel-client/docs/onboarding.md.

Do not use an admin key for the long-running runtime. Do not commit runtime keys, tunnel IDs, generated profiles, config.json, or .mcp.json.

First test in ChatGPT

Start a new ChatGPT conversation with the connector enabled and ask:

Call codex_status. Show only whether the bridge is healthy, the available tool names,
and the registered project names. Do not modify files.

Then test a read-only task:

Use codex_analyze on <PROJECT_PATH> to summarize the project structure and identify
the three highest-risk areas. Poll the job until it finishes and retrieve every output page.
Do not modify files.

For a write, ChatGPT must first call codex_prepare_apply, show you the exact plan, obtain your explicit confirmation, and only then call codex_apply with the returned token.

MCP tools

Security model

The trust boundary is intentionally narrow:

• Project access is limited to validated Codex project roots or explicit narrow roots.

• Sensitive directories such as .ssh, .aws, .gnupg, .kube, .config, and Library are rejected during automatic discovery.

• Codex subprocesses receive a minimal environment and run with explicit sandbox modes.

• Write tokens expire, are single-use, and are bound to the exact project and request.

• Session output is filtered to user-visible messages and redacted before leaving the machine.

• Request, output, scan, concurrency, retention, and timeout limits are bounded.

• ChatGPT context is treated as untrusted input and cannot override local policy.

Read docs/security-model.md before exposing the bridge to a team. Vulnerability reports should follow SECURITY.md.

Operational limits

Default limits are documented in config.example.json and enforced at startup. Important defaults include two concurrent jobs, 30-minute completed-job retention, a 120,000-character request ceiling, paginated 100,000-character job output, and bounded streaming scans for project history.

scan_complete answers whether the configured source scan finished. context_complete separately answers whether all scanned text fit in the returned context budget. A complete scan is not the same as an unbounded export.

Development

./scripts/bootstrap.sh
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q \
  bridge_core.py conversation_catalog.py desktop_assignment.py \
  desktop_sessions.py project_context.py server.py

See CONTRIBUTING.md for contribution rules and docs/architecture.md for module boundaries.

License

Apache License 2.0. See LICENSE.