codex-from-chatgpt

Use ChatGPT as the architect and orchestrator, while your local Codex does the actual work on your machine.

A personal, single-user MCP bridge. ChatGPT sends an instruction, the local service turns it into a codex app-server --stdio thread, and returns a compact summary of what Codex did.

Why

Codex is already good at doing the work. What it does not have is someone to decide what work to do, review the result, and push back. That is the part you normally do by hand, one prompt at a time.

This bridge puts ChatGPT in that seat. It plans, delegates, reads the diff, and sends the next instruction — while every command and file change happens on your machine, in your real repository, under approvals you control.

You: "Investigate this bug and fix it."

ChatGPT
  → starts a local Codex job
  → reviews the result
  → asks Codex for a correction
  → starts an independent review
  → handles approvals with you

Codex works on your actual local repo.

Dogfooded: v0.3 was developed using v0.2 — ChatGPT orchestrated local Codex implementation and independent review through this MCP. See Built using itself.

Community project, not official: this is not an official OpenAI or ChatGPT integration.

Architecture

The product boundary is deliberately small:

ChatGPT (through a Secure MCP Tunnel)
  -> MCP Streamable HTTP (/mcp)
  -> compact job API
  -> codex app-server --stdio (JSONL)
  -> local Codex

It does not use codex mcp-server, does not expose shell or filesystem as MCP tools, and implements no broker, worker farm, or external storage.

It also does not implement its own multi-agent framework — and does not need one. ChatGPT can orchestrate multiple independent Codex jobs through the same five-tool API: one job implements, another reviews it, and ChatGPT arbitrates between them.

Built using itself

codex-from-chatgpt was built and validated through the same loop it exposes: ChatGPT coordinated tasks over MCP, the bridge created local Codex threads, and the app-server returned snapshots to review the result. That loop was used for the implementation, follow-ups, independent reviews, and for answering Codex approvals.

The same loop maintains it. Using the five tools described below:

1. Use codex_start to investigate a change and its risks.
2. Use codex_continue to implement or fix one concrete part.
3. Use codex_get to review the standard handoff; request debug only when the bounded command log or diff is needed.
4. Use codex_respond_approval to answer specific approvals via their exact request_id.
5. Run independent reviews, then npm run typecheck, npm test, and git diff --check before calling a change done.

The idea is that the bridge is both the development tool and the artifact that documents how it is used.

Requirements

• Node.js 20 or later.

• Codex CLI on your PATH, installed and authenticated locally. Tested against Codex CLI 0.147.0 (app-server v2); other versions may work, and the installed binary is always the authority — see Protocol compatibility.

• A workspace directory under the allowed administrative root. That root defaults to ~/workspace and must exist:

  mkdir -p ~/workspace
  

• An OpenAI Platform account that can create tunnels, and a ChatGPT workspace where you can enable developer mode (see Plan availability).

Check your local Codex before wiring anything up:

codex --version

Setup overview

The full path from a clean clone to a working Codex job:

clone -> install -> configure -> run locally
      -> install tunnel-client -> configure tunnel -> doctor -> run tunnel
      -> connect in ChatGPT -> verify tools -> first Codex job

Each step below corresponds to one stage of that sequence.

1. Clone, install, run locally

git clone https://github.com/joseanu/codex-from-chatgpt.git
cd codex-from-chatgpt
npm install
npm run build
npm start

The process listens on loopback only by default:

• MCP: http://127.0.0.1:8787/mcp
• health: http://127.0.0.1:8787/healthz
• readiness: http://127.0.0.1:8787/readyz

2. Verify the local service

In a second terminal, confirm both the service and the Codex app-server are up. /readyz returns 503 until the app-server has initialized:

curl -fsS http://127.0.0.1:8787/healthz
curl -fsS http://127.0.0.1:8787/readyz

To use a different administrative root or port:

CODEX_WORKSPACE_ROOT=/absolute/path/to/workspaces PORT=8787 npm start

Leave this process running. Everything below assumes it is up.

3. Install tunnel-client

ChatGPT does not connect directly to 127.0.0.1. OpenAI's supported path for a local MCP server is the Secure MCP Tunnel, run by tunnel-client — a customer-run agent that bridges a private or localhost MCP server to ChatGPT and Codex over long-polling HTTPS, keeping the server off the public internet.

ChatGPT
  -> OpenAI control plane
  -> tunnel-client (on your machine)
  -> http://127.0.0.1:8787/mcp
  -> codex-from-chatgpt
  -> codex app-server --stdio

Get the binary from the OpenAI Platform under Tunnels, or from the release archives. Docker images are published at ghcr.io/openai/tunnel-client. To build from source:

go build -o bin/tunnel-client ./cmd/client

OpenAI recommends starting with the built-in guide:

tunnel-client help quickstart

Credentials, and where each one comes from

Credential	Env var	Used for	Where to create it
Tunnel ID	CONTROL_PLANE_TUNNEL_ID	Identifies your tunnel. Format: tunnel_ + 32 hex chars.	Platform → Tunnels, or tunnel-client admin tunnels create
Runtime API key	CONTROL_PLANE_API_KEY	The credential the daemon and doctor actually use.	Platform → API keys
Admin API key	OPENAI_ADMIN_KEY	Only for tunnel-client admin tunnels CRUD.	Platform → Admin keys

Do not use the admin key as the daemon credential — OpenAI's docs call this out explicitly. CONTROL_PLANE_API_KEY is the preferred variable; OPENAI_API_KEY is only a fallback when it is unset.

4. Configure the tunnel

Export the two runtime values:

export CONTROL_PLANE_API_KEY="sk-..."
export CONTROL_PLANE_TUNNEL_ID="tunnel_0123456789abcdef0123456789abcdef"

This project is an HTTP MCP server that is already running, so initialize from the remote-HTTP sample and bind the main channel to its local URL:

tunnel-client init --sample sample_mcp_remote_no_auth \
  --profile codex-from-chatgpt \
  --tunnel-id "$CONTROL_PLANE_TUNNEL_ID" \
  --mcp-server-url http://127.0.0.1:8787/mcp

The resulting profile is YAML, and the main channel is required:

config_version: 1
control_plane:
  tunnel_id: tunnel_0123456789abcdef0123456789abcdef
  api_key: env:CONTROL_PLANE_API_KEY
  base_url: https://api.openai.com
mcp:
  server_urls:
    - channel: main
      url: http://127.0.0.1:8787/mcp

Profiles are discovered under $XDG_CONFIG_HOME/tunnel-client or ~/.config/tunnel-client; a single config file can also be passed with --config or TUNNEL_CLIENT_CONFIG.

5. Doctor, then run the tunnel

Validate before starting the daemon:

tunnel-client doctor --profile codex-from-chatgpt --explain

Then run it in the foreground, in its own terminal:

tunnel-client run --profile codex-from-chatgpt

Host header: /mcp validates the Host header against the configured HOST:PORT and rejects anything else with 403 (see Security and limits). If your tunnel forwards its own hostname instead of the loopback upstream, add it with CODEX_AGENT_ALLOWED_HOSTS and restart this service.

6. Connect it in ChatGPT

Full MCP connectors live behind developer mode. An admin or owner enables it in Workspace Settings → Permissions & Roles → Connected Data → Developer mode / Create custom MCP connectors. Then create the custom MCP app pointing at your tunnel, let ChatGPT scan the tools, and enable it for your chats. Do not enter a 127.0.0.1 URL in ChatGPT — it cannot reach it.

Plan availability

Full MCP support including write actions is in beta for ChatGPT Business, Enterprise, and Edu on ChatGPT web. Pro users can build apps with the Apps SDK and use custom apps in deep research, but for read/fetch actions only.

This matters here: the five tools below are not read-only — they start Codex turns that run commands and change files. On a plan limited to read/fetch, this bridge will not work as intended. This project promises no universal support; only the capabilities your connected ChatGPT environment exposes will be available.

7. Verify the tools

After the scan, ChatGPT should list exactly five tools: codex_start, codex_get, codex_continue, codex_interrupt, and codex_respond_approval. If they are missing, re-check tunnel-client doctor and /readyz before touching anything in ChatGPT.

8. First Codex job

Ask for something read-only first, with an absolute workspace path under the allowed root:

Use codex_start in the workspace "/Users/you/workspace/my-project"
to inspect the git status without modifying any files. Give me the job_id,
then check the result with codex_get.

The normal flow is:

1. codex_start creates the persistent thread and begins the first turn.
2. codex_get returns the revision-aware job snapshot (standard by default).
3. When a turn finishes, codex_continue sends the next instruction to the same thread.
4. If Codex asks for an approval, codex_respond_approval answers it using the exact request_id from pending_approvals.
5. codex_interrupt stops an active turn when needed.

MCP tools

The public surface is exactly this:

Tool	Schema	Semantics
codex_start	{ workspace: string, prompt: string }	Validates the workspace, creates a persistent thread, starts a turn.
codex_get	{ job_id: string, detail?: "compact" | "standard" | "debug", since_revision?: number }	Returns a revision-aware job snapshot; standard is the default.
codex_continue	{ job_id: string, prompt: string }	Reuses the same thread and starts another turn once the previous one ended.
codex_interrupt	{ job_id: string }	Runs turn/interrupt on the active turn.
codex_respond_approval	{ job_id: string, request_id: string | number, decision: ... }	Answers one specific app-server approval.

codex_get has three deliberately different payload sizes:

• compact is for polling: status, revision, current activity, and critical errors or approvals.
• standard is the default supervisory handoff. While running it includes useful activity and changed files; after completion it includes the final message, files, deterministic diffstat, and recognized validation results, without the full command log or patch.
• debug includes bounded commands_executed and latest_diff fields for diagnosis. The underlying state remains available for recovery and is not discarded when standard hides it.

Pass since_revision from the previous response to suppress unchanged compact/ standard supervisory payloads; debug is always an on-demand current diagnostic snapshot. An unchanged response is intentionally tiny (status, revision, and unchanged: true), but pending approvals and errors are still surfaced. The revision is persisted per job and tracks supervisory/control-plane state. Debug-only command history and raw diff changes can update without advancing it.

Recommended flow: save the revision from codex_start, poll with compact and since_revision, then when the job completes call codex_get with detail: "standard" and no cursor for the final handoff. The cursor means “I know this supervisory state”, not “I have seen this detail view”, so a standard request with the same revision may also be unchanged; unchanged responses omit already-known warnings, while pending approvals and errors remain visible.

Every persistent thread also receives one short internal completion-handoff requirement automatically. It asks Codex's final response to state actions, files changed, validation and results, plus unresolved warnings or limitations; the caller's original prompt remains intact, and the requirement is not repeated on every continuation.

Approvals include their exact request_id, kind, and enough detail to choose a decision even in compact or unchanged polling responses. pending_approval remains an alias for the first approval, while pending_approvals carries all currently pending approvals. The bridge never returns the raw JSONL stream.

Approvals accept only the values and objects defined by the installed protocol for command execution, file changes, permissions, and legacy approvals. request_id is mandatory: two approvals can be pending at once, and one is never answered by position or by "the last one received".

Lifecycle, persistence, and recovery

States are starting, running, awaiting_approval, interrupting, completed, interrupted, failed, and recovery_required.

v0.3 allows a single active turn per process/app-server. A concurrent start or continue returns a semantic backend-busy error; interrupt remains available for the active turn. A process failure or a timeout with an uncertain outcome leaves the job in recovery_required — never in an invented completed.

The minimal job_id → thread_id index, workspace, last turn, and summary are written atomically to a local file. Its location can be set with CODEX_AGENT_STATE_FILE. Its contents may include final messages, diffs, files, commands, and errors, so treat it as potentially sensitive.

On app-server initialization, persisted jobs are rehydrated via thread/read and, where applicable, thread/resume. If the state cannot be proven, the job stays in recovery_required rather than silently becoming completed.

Security and limits

• The service binds to 127.0.0.1 by default.
• /mcp validates the Host header against the configured HOST:PORT and answers 403 to anything else. This closes DNS rebinding: a website the user visits cannot resolve its own domain to 127.0.0.1 and talk to the local service. Add extra hostnames with CODEX_AGENT_ALLOWED_HOSTS if the tunnel rewrites Host.
• The workspace must be absolute, existing, and under the allowed root.
• NUL bytes, .. segments, invalid roots, and symlink escapes after realpath are rejected.
• The remote client cannot choose config, model, sandbox, or permissions; environment overrides are administrative and local to the process.
• These tools are not read-only. Review Codex approvals before accepting commands, file changes, or permissions.
• Non-loopback binds require the explicit opt-in CODEX_AGENT_ALLOW_NON_LOOPBACK=1, and only when a tunnel covers the whole transport. The tunnel is not part of this repository.

Administrative configuration

• HOST and PORT: default 127.0.0.1:8787.
• CODEX_AGENT_ALLOW_NON_LOOPBACK=1: permits a non-loopback bind, only with equivalent external protection.
• CODEX_AGENT_ALLOWED_HOSTS: comma-separated extra hostnames accepted in the Host header on /mcp. Only needed if the tunnel forwards its own Host instead of the loopback upstream.
• CODEX_BIN: local binary; defaults to codex.
• CODEX_RPC_TIMEOUT_MS: generic RPC timeout; defaults to 30000 ms.
• CODEX_SHUTDOWN_TIMEOUT_MS: graceful shutdown wait; defaults to 2000 ms.
• CODEX_AGENT_STATE_FILE: optional state JSON location.
• CODEX_WORKSPACE_ROOT: optional administrative root; defaults to ~/workspace. Must be an existing absolute path.
• CODEX_AGENT_MODEL and CODEX_AGENT_REASONING_EFFORT: optional local overrides; without them Codex uses its own local configuration.

Protocol compatibility

The implementation is pinned against the observed protocol of codex-cli 0.147.0, app-server v2. The installed binary is the authority: OpenAI/Codex can change independently of your local CLI.

The client uses initialize → initialized, bidirectional JSONL, and the required RPCs thread/start, thread/resume, thread/list, thread/read, turn/start, and turn/interrupt, plus server-initiated approvals.

The generated TypeScript bindings in protocol/codex-0.147.0-ts/ are tracked because the code imports them for build-time type safety.

The JSON schemas are not tracked — nothing in the runtime or the build consumes them, so the repository does not carry hundreds of derived files. If you want them as a protocol reference, generate them against your installed binary:

codex app-server generate-json-schema --out protocol/codex-0.147.0-json-schema

That directory is in .gitignore. To move the pin to another version, install and verify the new CLI and regenerate the bindings:

codex app-server generate-ts --out protocol/codex-<version>-ts

Then review imports, approvals, and tests against the installed binary.

Local validation

npm run typecheck
npm test
npm run build
git diff --check

The optional integration test against the installed binary:

CODEX_REAL_APP_SERVER=1 npm test -- --test-name-pattern='installed codex'

Documentation and sources

Official OpenAI documentation this project is built against:

• Secure MCP Tunnel guide
• openai/tunnel-client
• tunnel-client onboarding
• tunnel-client configuration reference
• tunnel-client permissions
• tunnel-client troubleshooting
• Developer mode and MCP apps in ChatGPT
• MCP in ChatGPT
• Codex App Server

Everything outside those interfaces — the job model, the compact snapshot, the approval routing by request_id, the recovery semantics, and the workspace validation — is this project's own design.

License

MIT. See LICENSE.